Script compilation with MSBuild (Experimental)

Compile scripts with MSBuild as an experimental alternative to the default Unity script compilation pipeline.

Read time 9 minutes

Last updated 13 days ago

Important

Script compilation with MSBuild is an experimental feature in this version of Unity. It's provided as a technical preview for functional testing and validation and is not suitable for production use.

By default Unity compiles scripts with its own script compilation pipeline, which determines what gets compiled automatically based on folder names, file locations, and assembly definition (.asmdef) files. The default pipeline generates C# project (.csproj) files but they aren't authoritative. It also doesn't support NuGet natively, and references are resolved through

.asmdef

references, plug-ins in the

Assets

folder, and Unity packages.

MSBuild (Microsoft Build Engine) is the build platform for .NET and Visual Studio and is available experimentally as an alternative script compilation pipeline. MSBuild differs from Unity's default script compilation pipeline in the following ways:

MSBuild is an explicit system where what's compiled is determined by authoritative project (.csproj) and solution (.slnx) files that list files, references, and build targets.
MSBuild supports NuGet natively and handles dependency resolution via explicit
```
<PackageReference>
```
and
```
<ProjectReference>
```
entries.

There are some Unity-specific limitations to the support for MSBuild features. For more informaton, refer to MSBuild feature support in Unity

Enable script compilation with MSBuild

You can enable script compilation with MSBuild in one of the following ways:

Through the Editor Settings menu in the Unity Editor. Perform the following steps to activate MSBuild compilation through the Editor Settings menu:
1. Go to Edit >
  Project Settings
  ?
  .
2. Click on the Editor tab to open the Editor settings.
3. Navigate to the Script Compilation section heading.
4. Select the Enable MSBuild Compilation (Experimental) checkbox.
By supplying the Editor command-line argument
```
-enable-msbuild
```
.

In either case the Editor must be restarted for the change to take effect.

MSBuild files reference

When MSBuild compilation is enabled, the following files appear at the project root. In some cases you can edit these files and your changes are preserved. In other cases Unity controls the file contents and changes you make are overwritten. For further details, refer to the table:

File	Editable	Description
`Main.EntryPoint.csproj`	Yes (write-once)	Unity creates this file if missing and never overwrites it. You can add elements such as PropertyGroups, targets, and imports to this file and your changes are preserved.
`global.json`	Partially.	User keys and extra `msbuild-sdks` entries are preserved. Unity forces `sdk.version="8.0.0"` , `sdk.rollForward="latestMinor"` , and the four Unity SDK entries ( `Unity.Sdk` , `Unity.EntryPoint.Sdk` , `Unity.Test.Sdk` , `Microsoft.Build.Traversal` ).
`NuGet.config`	Partially.	Unity forces a single entry: `<add key="Unity Source" value="..."/>` under `<packageSources>` . Everything else (credentials, disabled sources, custom sources, config) is preserved.
`{project-name}.slnx`	Partially (if Unity-generated)	Filename controlled by `<SolutionGenerationName>` in `Main.EntryPoint.csproj` .
`Assets/*/.csproj` ( `.gen.csproj` )	No.	Regenerated from assembly definition on every signature change. Don't attempt to manually edit.
`Assets/*/.csproj` (no `.gen` suffix)	Yes.	Manually-authored .csproj files are supported. Unity's pattern-matching for file types detects and includes them in compilation automatically.

MSBuild feature support in Unity

All MSBuild features are supported in Unity projects unless documented otherwise in this section. For the authoritative reference on MSBuild features, refer to the Microsoft documentation.

Unsupported features

The following MSBuild features are not supported for Unity projects:

Unsupported feature	Description
Web / WPF / WinForms SDKs	`Microsoft.NET.Sdk.Web` , `Microsoft.NET.Sdk.Razor` , `Microsoft.NET.Sdk.Worker` , `Microsoft.NET.Sdk.WindowsDesktop` , `Microsoft.NET.Sdk.BlazorWebAssembly` and their child FrameworkReferences ( `Microsoft.AspNetCore.App` , `Microsoft.WindowsDesktop.App*` ) are out of scope for Unity project output.
Non-C# compilers (Vbc / Fsc)	Unity's assembly definition model and C# compilation pipeline assume C#. VB.NET and F# projects aren't supported.
COM Interop ( `<COMReference>` )	If you need COM, build a separate C# helper assembly with standard `dotnet build` and reference the output DLL via `Assets/Plugins/` .
Target frameworks above Net Standard 2.1	Manually authored .csproj files can technically set any `TargetFramework` value and MSBuild accepts it, builds the assembly, and copies it to `Library/ScriptAssemblies/HandLib.dll` . However, Unity scripting backends only support `netstandard2.1` (or opt-in `net10.0` via `enablelastdotnet.config` ). Don't rely on other target frameworks even though the build accepts them.
Multiple target frameworks	`<TargetFrameworks>net10.0;netstandard2.1</TargetFrameworks>` on a manually authored .csproj is accepted at the restore layer (both target frameworks appear in `project.assets.json` ), but the actual build produces a single DLL. Unity's assembly-loading pipeline is one DLL per assembly name and multiple target framework output is not supported.You can't ship a single project targeting multiple frameworks. If that's requird, produce one .csproj per target framework.

Limitations and best practices

The following section details MSBuild features that Unity supports to a limited extent and where particular workarounds or best practices apply.

Restrictions on use of NuGet

Unity doesn't support the use of NuGet as an alternative to the Unity Package Manager (UPM) for developing and distributing Unity Editor or Engine functionality. As such, Unity applies the following restrictions to the use of NuGet:

Any NuGet packages that use Unity APIs are blocked by the compilation pipeline.
Any UPM or Asset Store packages that import a NuGet package are blocked.
Any package that causes functional conflicts with Engine behavior or poses a security risk to users can be blocked at Unity's discretion.

Base class libraries (BCLs)

Unity bundles specific versions of several .NET libraries with an Editor installation. These versions are dependencies for certain Unity features and are chosen to align with Unity's internal .NET runtime version. The currently bundled packages are:

```
System.Text.Json
```
```
System.Collections.Immutable
```
```
System.Reflection.Metadata
```
```
System.Runtime.CompilerServices.Unsafe
```

Note

This list is expected to evolve as Unity's runtime and feature set change.

In the .NET assembly model it's not possible to have two versions of the same package present at once. If you add your own copy of one of the listed packages, Unity discards it and use its own bundled version instead.

A package you depend on that depends on a different version of one of these libraries will be resolved against Unity's version. In most cases this is transparent, but if your dependency requires an API surface that is not present in Unity's version, you might encounter incompatibilities.

MSBuild Restore

MSBuild in Unity supports both MSBuild restore and a faster NuGet restore engine. NuGet restore is the default and it bypasses MSBuild

Restore

targets entirely. Any

<Target Name="…" BeforeTargets="Restore">

AfterTargets="Restore"

hooks don't run under the default configuration. To switch to the MSBuild restore engine and make

Restore

target hooks run normally, launch the Editor with the

-disable-nuget-restore

command-line argument.

Custom property settings and targets

If you create

Directory.Build.props

and

Directory.Build.targets

files, they're disabled by default and setting

<ImportDirectoryBuildProps>true</ImportDirectoryBuildProps>

alone doesn't enable them. To enable them, you must also create the file

ProjectSettings/enableDirectoryBuild.config

. Even when enabled,

Directory.Build.*

is never applied to package projects or to

Main.EntryPoint.csproj

Prefer

UnityProject.Build.props

for project-wide extensions. It has the same reach as an enabled

Directory.Build.props

for user projects, without requiring the config file.

Custom build configurations

<Configurations>

UnityProject.Build.props

accepts additional entries (for example,

Custom+Beta

) without error, but the Editor UI never selects them for its own compilation invocations. The Editor only recognizes standard build configurations configurable through the UI. For more information, refer to Introduction to building.

You can define custom configurations for direct

dotnet build -p:Configuration=Custom+Beta

invocations from the command line, but the Editor never builds with them. The C# preprocessor defines added under a custom configuration are not active in Editor-driven builds.

Output paths for Unity assemblies

Unity uses the properties

OutputPath

IntermediateOutputPath

PublishDir

, and

UnityOutputDir

to define intermediate and output paths to

Library/MSBuild/artifacts/{obj,bin,Publish}

and copies final DLLs to

Library/ScriptAssemblies/

. These are critical for the Editor's assembly discovery. Overriding them on a

Unity.Sdk

.csproj breaks the Editor's ability to find the compiled assembly.

Framework reference not supported with .NET Standard 2.1

Any

FrameworkReference

item, such as

<FrameworkReference Include="Microsoft.NETCore.App"/>

, fails with

NETSDK1073: The FrameworkReference '…' was not recognized

with Unity's default

TargetFramework=netstandard2.1

FrameworkReference

by design requires a

net5+

netcore

target framework. To use it, you must opt into

net10.0

via

enablelastdotnet.config

Build events

The property form of build events works. For example,

<PreBuildEvent>echo hello</PreBuildEvent>

fires an

echo

command correctly. Some Visual Studio specific macros inside the string (such as

$(SolutionDir)

might work depending on evaluation context, but others such as

$(ProjectDir)

that assume the legacy .csproj format might not always expand. Prefer the target-based form (

<Target Name="X" BeforeTargets="PreBuildEvent">

Disabling Unity's package source

Never disable the package source

Unity Source

unless you have an alternative way to find Unity SDK packages. Adding

<disabledPackageSources><add key="Unity Source" value="true"/></disabledPackageSources>

NuGet.config

disables Unity's own SDK feed and Unity's

MaintainNugetConfig

doesn't re-enable it. Restore continues to succeed as long as the Unity SDK packages are already in the local NuGet cache, but on a fresh cache, restore of

Unity.Sdk

(and the other Unity MSBuild SDKs) fails.

Third-party SDKs via Nuget SDK resolution

Third-party SDKs, such as Microsoft.Build.NoTargets, referenced via

<Project Sdk="Name/version">

(NuGet-based SDK resolution) don't inherit Unity's output-path overrides, so

obj/

and

bin/

land inside

Assets/…/

and clutter the Asset Database.

Place third-party SDK .csproj files inside a folder suffixed with

, for example

Assets/OrchLib~/OrchLib.csproj

. The folder is then excluded from the auto-include, so you must explicitly reference it with

<ProjectReference Include="OrchLib~/OrchLib.csproj"/>

from

Main.EntryPoint.csproj

Assemblies referenced via package reference

Due to a known issue, analyzers and other assemblies referenced via

<PackageReference>

in manually-authored .csproj files might be restored but never run. Working alternatives are as follows:

Asset-labeled analyzers: Place the analyzer DLL under
```
Assets/
```
, set the asset's label to
```
RoslynAnalyzer
```
. For more information, refer to Create and use a Roslyn analyzer.
Scoped analyzers via
{AssemblyName}.Build.props
: Manually declare
```
<Analyzer Include="path/to/analyzer.dll"/>
```
in a
```
{name}.Build.props
```
next to an .asmdef-generated .csproj. Applies to direct referencers of that assembly.

Solution file maintenance

When you add and remove projects, for example by adding a new assembly definition or installing a package, their task correctly updates the solution (.slnx) file. Project membership within the solution correctly reflects the reference graph defined by

<ProjectReference>

entries. Unity doesn't overwrite custom solution folders and non-project sections.

Embedding resources

Default

EmbeddedResource

items are disabled. You must must explicitly

<EmbeddedResource Include="…"/>

, but the pipeline itself works.

.resx

files are compiled into

.resources

and embedded in the DLL. Satellite assemblies for culture variants (such as

Strings.fr.resx

producing

fr/{Name}.resources.dll

) are subject to whether the satellite DLL reaches

Library/ScriptAssemblies/

, which is subject to the same DLL pattern matching filter as any other output.

Documentation

Development

User Acquisition

Monetization

Industry

Unity Engine

User Manual

Script Reference