MSBuild reference for .NET Core SDK projects

This page is a reference for the MSBuild properties and items that you can use to configure .NET Core projects.

Note

This page is a work in progress and does not list all of the useful MSBuild properties for the .NET Core SDK. For a list of common MSBuild properties, see Common MSBuild properties.

Framework properties

TargetFramework

The TargetFramework property specifies the target framework version for the app, which implicitly references a metapackage. For a list of valid target framework monikers, see Target frameworks in SDK-style projects.

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>

For more information, see Target frameworks in SDK-style projects.

TargetFrameworks

Use the TargetFrameworks property when you want your app to target multiple platforms. For a list of valid target framework monikers, see Target frameworks in SDK-style projects.

Note

This property is ignored if TargetFramework (singular) is specified.

<PropertyGroup>
  <TargetFrameworks>netcoreapp3.1;net462</TargetFrameworks>
</PropertyGroup>

For more information, see Target frameworks in SDK-style projects.

NetStandardImplicitPackageVersion

Note

This property only applies to projects using netstandard1.x. It doesn't apply to projects that use netstandard2.x.

Use the NetStandardImplicitPackageVersion property when you want to specify a framework version that's lower than the metapackage version. The project file in the following example targets netstandard1.3 but uses the 1.6.0 version of NETStandard.Library.

<PropertyGroup>
  <TargetFramework>netstandard1.3</TargetFramework>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

Package properties

You can specify properties such as PackageId, PackageVersion, PackageIcon, Title, and Description to describe the package that gets created from your project. For information about these and other properties, see pack target.

<PropertyGroup>
  ...
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>John Doe</Authors>
  <Company>Contoso</Company>
</PropertyGroup>

Publish properties and items

RuntimeIdentifier

The RuntimeIdentifier property lets you specify a single runtime identifier (RID) for the project. The RID enables publishing a self-contained deployment.

<PropertyGroup>
  <RuntimeIdentifier>ubuntu.16.04-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

The RuntimeIdentifiers property lets you specify a semicolon-delimited list of runtime identifiers (RIDs) for the project. Use this property if you need to publish for multiple runtimes. RuntimeIdentifiers is used at restore time to ensure the right assets are in the graph.

Tip

RuntimeIdentifier (singular) can provide faster builds when only a single runtime is required.

<PropertyGroup>
  <RuntimeIdentifiers>win10-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>
</PropertyGroup>

TrimmerRootAssembly

The TrimmerRootAssembly item lets you exclude an assembly from trimming. Trimming is the process of removing unused parts of the runtime from a packaged application. In some cases, trimming might incorrectly remove required references.

The following XML excludes the System.Security assembly from trimming.

<ItemGroup>
  <TrimmerRootAssembly Include="System.Security" />
</ItemGroup>

UseAppHost

The UseAppHost property was introduced in the 2.1.400 version of the .NET Core SDK. It controls whether or not a native executable is created for a deployment. A native executable is required for self-contained deployments.

In .NET Core 3.0 and later versions, a framework-dependent executable is created by default. Set the UseAppHost property to false to disable generation of the executable.

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

For more information about deployment, see .NET Core application deployment.

Compile properties

EmbeddedResourceUseDependentUponConvention

The EmbeddedResourceUseDependentUponConvention property defines whether resource manifest file names are generated from type information in source files that are colocated with resource files. For example, if Form1.resx is in the same folder as Form1.cs, and EmbeddedResourceUseDependentUponConvention is set to true, the generated .resources file takes its name from the first type that's defined in Form1.cs. For example, if MyNamespace.Form1 is the first type defined in Form1.cs, the generated file name is MyNamespace.Form1.resources.

Note

If LogicalName, ManifestResourceName, or DependentUpon metadata is specified for an EmbeddedResource item, the generated manifest file name for that resource file is based on that metadata instead.

By default, in a new .NET Core project, this property is set to true. If set to false, and no LogicalName, ManifestResourceName, or DependentUpon metadata is specified for the EmbeddedResource item in the project file, the resource manifest file name is based off the root namespace for the project and the relative file path to the .resx file. For more information, see How resource manifest files are named.

<PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

LangVersion

The LangVersion property lets you specify a specific programming language version. For example, if you want access to C# preview features, set LangVersion to preview.

<PropertyGroup>
  <LangVersion>preview</LangVersion>
</PropertyGroup>

For more information, see C# language versioning.

Run-time configuration properties

You can configure some run-time behaviors by specifying MSBuild properties in the project file of the app. For information about other ways of configuring run-time behavior, see .NET Core run-time configuration settings.

ConcurrentGarbageCollection

The ConcurrentGarbageCollection property configures whether background (concurrent) garbage collection is enabled. Set the value to false to disable background garbage collection. For more information, see System.GC.Concurrent/COMPlus_gcConcurrent.

<PropertyGroup>
  <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
</PropertyGroup>

InvariantGlobalization

The InvariantGlobalization property configures whether the app runs in globalization-invariant mode, which means it doesn't have access to culture-specific data. Set the value to true to run in globalization-invariant mode. For more information, see Invariant mode.

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

RetainVMGarbageCollection

The RetainVMGarbageCollection property configures the garbage collector to put deleted memory segments on a standby list for future use or release them. Setting the value to true tells the garbage collector to put the segments on a standby list. For more information, see System.GC.RetainVM/COMPlus_GCRetainVM.

<PropertyGroup>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
</PropertyGroup>

ServerGarbageCollection

The ServerGarbageCollection property configures whether the application uses workstation garbage collection or server garbage collection. Set the value to true to use server garbage collection. For more information, see System.GC.Server/COMPlus_gcServer.

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ThreadPoolMaxThreads

The ThreadPoolMaxThreads property configures the maximum number of threads for the worker thread pool. For more information, see Maximum threads.

<PropertyGroup>
  <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
</PropertyGroup>

ThreadPoolMinThreads

The ThreadPoolMinThreads property configures the minimum number of threads for the worker thread pool. For more information, see Minimum threads.

<PropertyGroup>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
</PropertyGroup>

TieredCompilation

The TieredCompilation property configures whether the just-in-time (JIT) compiler uses tiered compilation. Set the value to false to disable tiered compilation. For more information, see Tiered compilation.

<PropertyGroup>
  <TieredCompilation>false</TieredCompilation>
</PropertyGroup>

TieredCompilationQuickJit

The TieredCompilationQuickJit property configures whether the JIT compiler uses quick JIT. Set the value to false to disable quick JIT. For more information, see Quick JIT.

<PropertyGroup>
  <TieredCompilationQuickJit>false</TieredCompilationQuickJit>
</PropertyGroup>

TieredCompilationQuickJitForLoops

The TieredCompilationQuickJitForLoops property configures whether the JIT compiler uses quick JIT on methods that contain loops. Set the value to true to enable quick JIT on methods that contain loops. For more information, see Quick JIT for loops.

<PropertyGroup>
  <TieredCompilationQuickJitForLoops>true</TieredCompilationQuickJitForLoops>
</PropertyGroup>

Reference properties and items

AssetTargetFallback

The AssetTargetFallback property lets you specify additional compatible framework versions for project references and NuGet packages. For example, if you specify a package dependency using PackageReference but that package doesn't contain assets that are compatible with your projects's TargetFramework, the AssetTargetFallback property comes into play. The compatibility of the referenced package is rechecked using each target framework that's specified in AssetTargetFallback.

You can set the AssetTargetFallback property to one or more target framework versions.

<PropertyGroup>
  <AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>

PackageReference

The PackageReference item defines a reference to a NuGet package. For example, you may want to reference a single package instead of a metapackage.

The Include attribute specifies the package ID. The Version attribute specifies the version or version range. For information about how to specify a minimum version, maximum version, range, or exact match, see Version ranges. You can also add the following metadata to a project reference: IncludeAssets, ExcludeAssets, and PrivateAssets.

The project file snippet in the following example references the System.Runtime package.

<ItemGroup>
  <PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>

For more information, see Package references in project files.

ProjectReference

The ProjectReference item defines a reference to another project. The referenced project is added as a NuGet package dependency, that is, it's treated the same as a PackageReference.

The Include attribute specifies the path to the project. You can also add the following metadata to a project reference: IncludeAssets, ExcludeAssets, and PrivateAssets.

The project file snippet in the following example references a project named Project2.

<ItemGroup>
  <ProjectReference Include="..\Project2.csproj" />
</ItemGroup>

Reference

The Reference item defines a reference to an assembly file.

The Include attribute specifies the name of the file, and the HintPath metadata specifies the path to the assembly.

<ItemGroup>
  <Reference Include="MyAssembly">
    <HintPath>..\..\Assemblies\MyAssembly.dll</HintPath>
  </Reference>
</ItemGroup>

Restore properties

Restoring a referenced package installs all of its direct dependencies and all the dependencies of those dependencies. You can customize package restoration by specifying properties such as RestorePackagesPath and RestoreIgnoreFailedSources. For more information about these and other properties, see restore target.

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

See also