MSBuild compilation in Unity

Enable script compilation with MSBuild and understand the Unity-specific limitations to MSBuild features.

Read time 10 minutes

Last updated 7 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. Unity restricts which NuGet packages a project can use, and checks every restored package against a policy before it compiles any code. A package that violates the policy fails the build with the error

MSBU0006

MSBU0007

. You can't opt out of these checks.

Unity also bundles specific versions of several .NET base class libraries (BCLs) with an Editor installation, and resolves your project against those versions instead of any copy you add yourself.

For more information about the restrictions, the checks, and the bundled libraries, refer to NuGet package policy.

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

Importing analyzers

You can import code analyzers in several ways.

Referencing an analyzer in
{AssemblyName}.Build.props

If your project is using MSBuild compilation exclusively, you can add a reference to the analyzer in a

{AssemblyName}.Build.props

file, using

<Analyzer Include="path/to/analyzer.dll"/>

. This file is entirely user-authored and Unity never overwrites or modifies it.

{AssemblyName}

refers to the base name of the

.csproj

file, excluding any

.gen

suffix added by the conversion tool. For example, for a generated project named

AssemblyName.gen.csproj

, the props file is still

AssemblyName.Build.props

and not

AssemblyName.gen.Build.props

Note

{AssemblyName}.Build.props

is automatically imported only by projects that have a direct reference to

{AssemblyName}

. It's therefore applied to the referencing assemblies, not to

{AssemblyName}

itself. To make the analyzer also run on

{AssemblyName}

's own code, add a self-import so that

{AssemblyName}.csproj

imports

{AssemblyName}.Build.props

Importing an analyzer via an asset label (conversion workflow)

If your project is converting from assembly definition files to MSBuild compilation, place the analyzer DLL under

Assets/

and set the asset's label to

RoslynAnalyzer

. For more information, refer to Create and use a Roslyn analyzer. The analyzer scope is determined by the location of the DLL:

Global analyzers: A labeled DLL outside any assembly definition folder applies to every project, through
```
Library/MSBuild/UnityProps/Common/UnityRoslynAnalyzers.props
```
.
Scoped analyzers: A DLL inside an assembly definition folder applies only to that assembly and the assemblies that reference it, through
```
{AssemblyName}.Analyzers.gen.props
```
. The
```
{AssemblyName}.Analyzers.gen.props
```
file is automatically generated during conversion from .asmdef to .csproj.

Referencing an analyzer in a manually authored .csproj

In a manually authored .csproj file, you can also add the reference as a

<PackageReference>

in the .csproj file itself.

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