MSBuild reference for .NET SDK projects
This page is a reference for the MSBuild properties and items that you can use to configure .NET projects.
Note
This page is a work in progress and does not list all of the useful MSBuild properties for the .NET SDK. For a list of common MSBuild properties, see Common MSBuild properties.
Assembly validation properties
These properties and items are passed to the ValidateAssemblies
task. For more information about assembly validation, see Assembly validation.
The following MSBuild properties are documented in this section:
Note
These properties aren't part of the .NET SDK (yet). To use them, you must also add a PackageReference
to Microsoft.DotNet.ApiCompat.Task.
In addition, the following properties that are documented in the Package validation properties also apply to assembly validation:
- ApiCompatEnableRuleAttributesMustMatch
- ApiCompatEnableRuleCannotChangeParameterName
- ApiCompatExcludeAttributesFile
- ApiCompatGenerateSuppressionFile
- ApiCompatPermitUnnecessarySuppressions
- ApiCompatPreserveUnnecessarySuppressions
- ApiCompatRespectInternals
- ApiCompatSuppressionFile
- ApiCompatSuppressionOutputFile
- NoWarn
- RoslynAssembliesPath
ApiCompatStrictMode
When set to true
, the ApiCompatStrictMode
property specifies that API compatibility checks should be performed in strict mode.
<PropertyGroup>
<ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>
ApiCompatValidateAssemblies
The ApiCompatValidateAssemblies
property enables a series of validations on the specified assemblies. For more information, see Assembly validation.
<PropertyGroup>
<ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>
Framework properties
The following MSBuild properties are documented in this section:
TargetFramework
The TargetFramework
property specifies the target framework version for the app. For a list of valid target framework monikers, see Target frameworks in SDK-style projects.
<PropertyGroup>
<TargetFramework>net8.0</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>net8.0;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>
Assembly attribute properties
GenerateAssemblyInfo
The GenerateAssemblyInfo
property controls AssemblyInfo
attribute generation for the project. The default value is true
. Use false
to disable generation of the file:
<PropertyGroup>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>
The GeneratedAssemblyInfoFile setting controls the name of the generated file.
When the GenerateAssemblyInfo
value is true
, package-related project properties are transformed into assembly attributes.
For more information about generating assembly attributes using a project file, see Set assembly attributes in a project file.
GeneratedAssemblyInfoFile
The GeneratedAssemblyInfoFile
property defines the relative or absolute path of the generated assembly info file. Defaults to a file named [project-name].AssemblyInfo.[cs|vb] in the $(IntermediateOutputPath)
(usually the obj) directory.
<PropertyGroup>
<GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>
Package properties
Descriptive 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>
PackRelease
The PackRelease
property is similar to the PublishRelease property, except that it changes the default behavior of dotnet pack
. This property was introduced in .NET 7.
<PropertyGroup>
<PackRelease>true</PackRelease>
</PropertyGroup>
Note
- Starting in the .NET 8 SDK,
PackRelease
defaults totrue
. For more information, see 'dotnet pack' uses Release configuration. - .NET 7 SDK only: To use
PackRelease
in a project that's part of a Visual Studio solution, you must set the environment variableDOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS
totrue
(or any other value). For solutions that have many projects, setting this variable increases the time required to pack.
Package validation properties
These properties and items are passed to the ValidatePackage
task. For more information about package validation, see Package validation overview.
For properties for the ValidateAssemblies
task, see Assembly validation properties.
The following MSBuild properties and items are documented in this section:
- ApiCompatEnableRuleAttributesMustMatch
- ApiCompatEnableRuleCannotChangeParameterName
- ApiCompatExcludeAttributesFile
- ApiCompatGenerateSuppressionFile
- ApiCompatPermitUnnecessarySuppressions
- ApiCompatPreserveUnnecessarySuppressions
- ApiCompatRespectInternals
- ApiCompatSuppressionFile
- ApiCompatSuppressionOutputFile
- EnablePackageValidation
- EnableStrictModeForBaselineValidation
- EnableStrictModeForCompatibleFrameworksInPackage
- EnableStrictModeForCompatibleTfms
- NoWarn
- PackageValidationBaselineFrameworkToIgnore
- PackageValidationBaselineName
- PackageValidationBaselineVersion
- PackageValidationReferencePath
- RoslynAssembliesPath
ApiCompatEnableRuleAttributesMustMatch
When set to true
, the ApiCompatEnableRuleAttributesMustMatch
property enables the validation rule that checks if attributes match. The default is false
.
<PropertyGroup>
<ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
</PropertyGroup>
ApiCompatEnableRuleCannotChangeParameterName
When set to true
, the ApiCompatEnableRuleCannotChangeParameterName
property enables the validation rule that checks whether parameter names have changed in public methods. The default is false
.
<PropertyGroup>
<ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
</PropertyGroup>
ApiCompatExcludeAttributesFile
The ApiCompatExcludeAttributesFile
item specifies the path to a file that contains attributes to exclude in DocId format.
<ItemGroup>
<ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
<ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
</ItemGroup>
ApiCompatGenerateSuppressionFile
The ApiCompatGenerateSuppressionFile
property specifies whether to generate a compatibility suppression file.
<PropertyGroup>
<ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
</PropertyGroup>
ApiCompatPermitUnnecessarySuppressions
The ApiCompatPermitUnnecessarySuppressions
property specifies whether to permit unnecessary suppressions in the suppression file.
The default is false
.
<PropertyGroup>
<ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
</PropertyGroup>
ApiCompatPreserveUnnecessarySuppressions
The ApiCompatPreserveUnnecessarySuppressions
property specifies whether to preserve unnecessary suppressions when regenerating the suppression file. When an existing suppression file is regenerated, its content is read, deserialized into a set of suppressions, and then stored in a list. Some of the suppressions might no longer be necessary if the incompatibility has been fixed. When the suppressions are serialized back to disk, you can choose to keep all the existing (deserialized) expressions by setting this property to true
.
The default is false
.
<PropertyGroup>
<ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
</PropertyGroup>
ApiCompatRespectInternals
The ApiCompatRespectInternals
property specifies whether internal
APIs should be checked for compatibility in addition to public
APIs.
<PropertyGroup>
<ApiCompatRespectInternals>true</ApiCompatRespectInternals>
</PropertyGroup>
ApiCompatSuppressionFile
The ApiCompatSuppressionFile
item specifies the path to one or more suppression files to read from. If unspecified, the suppression file <project-directory>/CompatibilitySuppressions.xml is read (if it exists).
<ItemGroup>
<ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
</ItemGroup>
ApiCompatSuppressionOutputFile
The ApiCompatSuppressionOutputFile
property specifies the path to a suppression file to write to when <ApiCompatGenerateSuppressionFile>
is true
. If unspecified, the first ApiCompatSuppressionFile
item is used.
EnablePackageValidation
The EnablePackageValidation
property enables a series of validations on the package after the Pack
task. For more information, see package validation.
<PropertyGroup>
<EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>
EnableStrictModeForBaselineValidation
When set to true
, the EnableStrictModeForBaselineValidation
property enables strict mode for package baseline checks. The default is false
.
EnableStrictModeForCompatibleFrameworksInPackage
When set to true
, the EnableStrictModeForCompatibleFrameworksInPackage
property enables strict mode for assemblies that are compatible based on their target framework. The default is false
.
EnableStrictModeForCompatibleTfms
When set to true
, the EnableStrictModeForCompatibleTfms
property enables strict mode for contract and implementation assemblies for all compatible target frameworks. The default is true
.
NoWarn
The NoWarn
property specifies the diagnostic IDs to suppress.
<PropertyGroup>
<NoWarn>$(NoWarn);PKV0001</NoWarn>
</PropertyGroup>
PackageValidationBaselineFrameworkToIgnore
The PackageValidationBaselineFrameworkToIgnore
item specifies a target framework to ignore from the baseline package. The framework string must exactly match the folder name in the baseline package.
<ItemGroup>
<PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
</ItemGroup>
PackageValidationBaselineName
The PackageValidationBaselineName
property specifies the name of the baseline package to validate the current package against. If unspecified, the PackageId
value is used.
PackageValidationBaselineVersion
The PackageValidationBaselineVersion
property specifies the version of the baseline package to validate the current package against.
PackageValidationReferencePath
The PackageValidationReferencePath
item specifies the directory path where the reference assembly can be found per TFM.
<ItemGroup>
<PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
</ItemGroup>
RoslynAssembliesPath
The RoslynAssembliesPath
property specifies the path to the directory that contains the Microsoft.CodeAnalysis assemblies you want to use. You only need to set this property if you want to test with a newer compiler than what's in the SDK.
Publish-related properties
The following MSBuild properties are documented in this section:
- AppendRuntimeIdentifierToOutputPath
- AppendTargetFrameworkToOutputPath
- CopyLocalLockFileAssemblies
- ErrorOnDuplicatePublishOutputFiles
- GenerateRuntimeConfigDevFile
- GenerateRuntimeConfigurationFiles
- GenerateSatelliteAssembliesForCore
- IsPublishable
- PreserveCompilationContext
- PreserveCompilationReferences
- ProduceReferenceAssemblyInOutDir
- PublishDocumentationFile
- PublishDocumentationFiles
- PublishReferencesDocumentationFiles
- PublishRelease
- PublishSelfContained
- RollForward
- RuntimeFrameworkVersion
- RuntimeIdentifier
- RuntimeIdentifiers
- SatelliteResourceLanguages
- SelfContained
- UseAppHost
AppendTargetFrameworkToOutputPath
The AppendTargetFrameworkToOutputPath
property controls whether the target framework moniker (TFM) is appended to the output path (which is defined by OutputPath). The .NET SDK automatically appends the target framework and, if present, the runtime identifier to the output path. Setting AppendTargetFrameworkToOutputPath
to false
prevents the TFM from being appended to the output path. However, without the TFM in the output path, multiple build artifacts may overwrite each other.
For example, for a .NET 5 app, the output path changes from bin\Debug\net5.0
to bin\Debug
with the following setting:
<PropertyGroup>
<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>
AppendRuntimeIdentifierToOutputPath
The AppendRuntimeIdentifierToOutputPath
property controls whether the runtime identifier (RID) is appended to the output path. The .NET SDK automatically appends the target framework and, if present, the runtime identifier to the output path. Setting AppendRuntimeIdentifierToOutputPath
to false
prevents the RID from being appended to the output path.
For example, for a .NET 5 app and an RID of win-x64
, the following setting changes the output path from bin\Debug\net5.0\win-x64
to bin\Debug\net5.0
:
<PropertyGroup>
<AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>
CopyLocalLockFileAssemblies
The CopyLocalLockFileAssemblies
property is useful for plugin projects that have dependencies on other libraries. If you set this property to true
, any transitive NuGet package dependencies are copied to the output directory. That means you can use the output of dotnet build
to run your plugin on any machine.
<PropertyGroup>
<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>
The default value of CopyLocalLockFileAssemblies
can vary based on the output type. For example, for class libraries the default value is false
, while for console applications the default is true
. You can specify this property explicitly to override the default if needed.
Tip
Alternatively, you can use dotnet publish
to publish the class library. For more information, see dotnet publish.
ErrorOnDuplicatePublishOutputFiles
The ErrorOnDuplicatePublishOutputFiles
property relates to whether the SDK generates error NETSDK1148 when MSBuild detects duplicate files in the publish output, but can't determine which files to remove. Set the ErrorOnDuplicatePublishOutputFiles
property to false
if you don't want the error to be generated.
<PropertyGroup>
<ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>
This property was introduced in .NET 6.
GenerateRuntimeConfigDevFile
Starting with the .NET 6 SDK, the [Appname].runtimesettings.dev.json file is no longer generated by default at compile time. If you still want this file to be generated, set the GenerateRuntimeConfigDevFile
property to true
.
<PropertyGroup>
<GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>
GenerateRuntimeConfigurationFiles
The GenerateRuntimeConfigurationFiles
property controls whether runtime configuration options are copied from the runtimeconfig.template.json file to the [appname].runtimeconfig.json file. For apps that require a runtimeconfig.json file, that is, those whose OutputType
is Exe
, this property defaults to true
.
<PropertyGroup>
<GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>
GenerateSatelliteAssembliesForCore
The GenerateSatelliteAssembliesForCore
property controls whether satellite assemblies are generated using csc.exe or Al.exe (Assembly Linker) in .NET Framework projects. (.NET Core and .NET 5+ projects always use csc.exe to generate satellite assemblies.) For .NET Framework projects, satellite assemblies are created by al.exe, by default. By setting the GenerateSatelliteAssembliesForCore
property to true
, satellite assemblies are created by csc.exe instead. Using csc.exe can be advantageous in the following situations:
- You want to use the C# compiler
deterministic
option. - You're limited by the fact that al.exe has no support for public signing and handles AssemblyInformationalVersionAttribute poorly.
<PropertyGroup>
<GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>
IsPublishable
The IsPublishable
property allows the Publish
target to run. This property only affects processes that use .*proj files and the Publish
target, such as the dotnet publish command. It does not affect publishing in Visual Studio, which uses the PublishOnly
target. The default value is true
.
This property is useful if you run dotnet publish
on a solution file, as it allows automatic selection of projects that should be published.
<PropertyGroup>
<IsPublishable>false</IsPublishable>
</PropertyGroup>
PreserveCompilationContext
The PreserveCompilationContext
property allows a built or published application to compile more code at run time using the same settings that were used at build time. The assemblies referenced at build time will be copied into the ref subdirectory of the output directory. The names of the reference assemblies are stored in the application's .deps.json file along with the options passed to the compiler. You can retrieve this information using the DependencyContext.CompileLibraries and DependencyContext.CompilationOptions properties.
This functionality is mostly used internally by ASP.NET Core MVC and Razor pages to support run-time compilation of Razor files.
<PropertyGroup>
<PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>
PreserveCompilationReferences
The PreserveCompilationReferences
property is similar to the PreserveCompilationContext property, except that it only copies the referenced assemblies to the publish directory, and not the .deps.json file.
<PropertyGroup>
<PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>
For more information, see Razor SDK properties.
ProduceReferenceAssemblyInOutDir
In .NET 5 and earlier versions, reference assemblies are always written to the OutDir
directory. In .NET 6 and later versions, you can use the ProduceReferenceAssemblyInOutDir
property to control whether reference assemblies are written to the OutDir
directory. The default value is false
, and reference assemblies are only written to the IntermediateOutputPath
directory. Set the value to true
to write reference assemblies to the OutDir
directory.
<PropertyGroup>
<ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>
For more information, see Write reference assemblies to intermediate output.
PublishDocumentationFile
When this property is true
, the XML documentation file for the project, if one is generated, is included in the publish output for the project. This property defaults to true
.
Tip
Set GenerateDocumentationFile to true
to generate an XML documentation file at compile time.
PublishDocumentationFiles
This property is an enablement flag for several other properties that control whether various kinds of XML documentation files are copied to the publish directory by default, namely PublishDocumentationFile and PublishReferencesDocumentationFiles. If those properties are unset, and this property is set, then those properties will default to true
. This property defaults to true
.
PublishReferencesDocumentationFiles
When this property is true
, XML documentation files for the project's references are copied to the publish directory, instead of just run-time assets like DLL files. This property defaults to true
.
PublishRelease
The PublishRelease
property informs dotnet publish
to use the Release
configuration by default instead of the Debug
configuration. This property was introduced in .NET 7.
<PropertyGroup>
<PublishRelease>true</PublishRelease>
</PropertyGroup>
Note
- Starting in the .NET 8 SDK,
PublishRelease
defaults totrue
for projects that target .NET 8 or later. For more information, see 'dotnet publish' uses Release configuration. - This property does not affect the behavior of
dotnet build /t:Publish
, and it only changes the configuration only when publishing via the .NET CLI. - .NET 7 SDK only: To use
PublishRelease
in a project that's part of a Visual Studio solution, you must set the environment variableDOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS
totrue
(or any other value). When publishing a solution with this variable enabled, the executable project'sPublishRelease
value takes precedence and flows the new default configuration to any other projects in the solution. If a solution contains multiple executable or top-level projects with differing values ofPublishRelease
, the solution won't successfully publish. For solutions that have many projects, use of this setting increases the time required to publish.
PublishSelfContained
The PublishSelfContained
property informs dotnet publish
to publish an app as a self-contained app. This property is useful when you can't use the --self-contained
argument for the dotnet publish command—for example, when you're publishing at the solution level. In that case, you can add the PublishSelfContained
MSBuild property to a project or Directory.Build.Props file.
This property was introduced in .NET 7. It's similar to the SelfContained property, except that it's specific to the publish
verb. It's recommended to use PublishSelfContained
instead of SelfContained
.
<PropertyGroup>
<PublishSelfContained>true</PublishSelfContained>
</PropertyGroup>
RollForward
The RollForward
property controls how the application chooses a runtime when multiple runtime versions are available. This value is output to the .runtimeconfig.json as the rollForward
setting.
<PropertyGroup>
<RollForward>LatestMinor</RollForward>
</PropertyGroup>
Set RollForward
to one of the following values:
Value | Description |
---|---|
Minor |
Default if not specified. Roll-forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the LatestPatch policy is used. |
Major |
Roll-forward to the next available higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the Minor policy is used. |
LatestPatch |
Roll-forward to the highest patch version. This value disables minor version roll-forward. |
LatestMinor |
Roll-forward to highest minor version, even if requested minor version is present. |
LatestMajor |
Roll-forward to highest major and highest minor version, even if requested major is present. |
Disable |
Don't roll-forward, only bind to the specified version. This policy isn't recommended for general use since it disables the ability to roll-forward to the latest patches. This value is only recommended for testing. |
For more information, see Control roll-forward behavior.
RuntimeFrameworkVersion
The RuntimeFrameworkVersion
property specifies the version of the runtime to use when publishing. Specify a runtime version:
<PropertyGroup>
<RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>
When publishing a framework-dependent application, this value specifies the minimum version required. When publishing a self-contained application, this value specifies the exact version required.
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>linux-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>win-x64;osx-x64;linux-x64</RuntimeIdentifiers>
</PropertyGroup>
SatelliteResourceLanguages
The SatelliteResourceLanguages
property lets you specify which languages you want to preserve satellite resource assemblies for during build and publish. Many NuGet packages include localized resource satellite assemblies in the main package. For projects that reference these NuGet packages that don't require localized resources, the localized assemblies can unnecessarily inflate the build and publish output size. By adding the SatelliteResourceLanguages
property to your project file, only localized assemblies for the languages you specify will be included in the build and publish output. For example, in the following project file, only English (US) and German (Germany) resource satellite assemblies will be retained.
<PropertyGroup>
<SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>
Note
You must specify this property in the project that references the NuGet package with localized resource satellite assemblies.
To specify multiple languages as an argument to
dotnet publish
, you must add three pairs of quotation marks around the language identifiers. For example:dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""
SelfContained
The SelfContained
property informs dotnet build
and dotnet publish
to build or publish an app as a self-contained app. This property is useful when you can't use the --self-contained
argument with the dotnet command—for example, when you're publishing at the solution level. In that case, you can add the SelfContained
MSBuild property to a project or Directory.Build.Props file.
This property is similar to the PublishSelfContained property. It's recommended to use PublishSelfContained
instead of SelfContained
when possible.
<PropertyGroup>
<SelfContained>true</SelfContained>
</PropertyGroup>
UseAppHost
The UseAppHost
property controls whether or not a native executable is created for a deployment. A native executable is required for self-contained deployments. 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 application deployment.
Trim-related properties
Numerous MSBuild properties are available to fine tune trimming, which is a feature that trims unused code from self-contained deployments. These options are discussed in detail at Trimming options. The following table provides a quick reference.
Property | Values | Description |
---|---|---|
PublishTrimmed |
true or false |
Controls whether trimming is enabled during publish. |
TrimMode |
full or partial |
Default is full . Controls the trimming granularity. |
SuppressTrimAnalysisWarnings |
true or false |
Controls whether trim analysis warnings are produced. |
EnableTrimAnalyzer |
true or false |
Controls whether a subset of trim analysis warnings are produced. You can enable analysis even if PublishTrimmed is set to false . |
ILLinkTreatWarningsAsErrors |
true or false |
Controls whether trim warnings are treated as errors. For example, you may want to set this property to false when TreatWarningsAsErrors is set to true . |
TrimmerSingleWarn |
true or false |
Controls whether a single warning per assembly is shown or all warnings. |
TrimmerRemoveSymbols |
true or false |
Controls whether all symbols are removed from a trimmed application. |
Build-related properties
The following MSBuild properties are documented in this section:
- ContinuousIntegrationBuild
- CopyDebugSymbolFilesFromPackages
- CopyDocumentationFilesFromPackages
- DisableImplicitFrameworkDefines
- DocumentationFile
- EmbeddedResourceUseDependentUponConvention
- EnablePreviewFeatures
- EnableWindowsTargeting
- GenerateDocumentationFile
- GenerateRequiresPreviewFeaturesAttribute
- OptimizeImplicitlyTriggeredBuild
- DisableRuntimeMarshalling
C# compiler options, such as LangVersion
and Nullable
, can also be specified as MSBuild properties in your project file. For more information, see C# compiler options.
ContinuousIntegrationBuild
The ContinuousIntegrationBuild
property indicates whether a build is executing on a continuous integration (CI) server. When set to true
, this property enables settings that only apply to official builds as opposed to local builds on a developer machine. For example, stored file paths are normalized for official builds. But on a local development machine, the debugger isn't able to find local source files if file paths are normalized.
Note
Currently, setting this property to true
works only if you add either a specific SourceLink provider package reference or a <SourceRoot Include="$(MyDirectory)" />
item. For more information, see dotnet/roslyn issue 55860.
You can use your CI system's variable to conditionally set the ContinuousIntegrationBuild
property. For example, the variable name for Azure Pipelines is TF_BUILD
:
<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>
For GitHub Actions, the variable name is GITHUB_ACTIONS
:
<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>
CopyDebugSymbolFilesFromPackages
When this property is set to true
, all symbol files (also known as PDB files) from PackageReference
items in the project are copied to the build output. These files can provide more informative stack traces for exceptions and make memory dumps and traces of the running application easier to understand. However, including these files results in an increased deployment bundle size.
This property was introduced in .NET SDK 7.0.100, though it defaults to not being specified.
CopyDocumentationFilesFromPackages
When this property is set to true
, all generated XML documentation files from PackageReference
items in the project are copied to the build output. Note that enabling this feature will result in increased deployment bundle size.
This property was introduced in .NET SDK 7.0.100, though it defaults to not being specified.
DisableImplicitFrameworkDefines
The DisableImplicitFrameworkDefines
property controls whether or not the SDK generates preprocessor symbols for the target framework and platform for the .NET project. When this property is set to false
or is unset (which is the default value) preprocessor symbols are generated for:
- Framework without version (
NETFRAMEWORK
,NETSTANDARD
,NET
) - Framework with version (
NET48
,NETSTANDARD2_0
,NET6_0
) - Framework with version minimum bound (
NET48_OR_GREATER
,NETSTANDARD2_0_OR_GREATER
,NET6_0_OR_GREATER
)
For more information on target framework monikers and these implicit preprocessor symbols, see Target frameworks.
Additionally, if you specify an operating system-specific target framework in the project (for example net6.0-android
), the following preprocessor symbols are generated:
- Platform without version (
ANDROID
,IOS
,WINDOWS
) - Platform with version (
IOS15_1
) - Platform with version minimum bound (
IOS15_1_OR_GREATER
)
For more information on operating system-specific target framework monikers, see OS-specific TFMs.
Finally, if your target framework implies support for older target frameworks, preprocessor symbols for those older frameworks are emitted. For example, net6.0
implies support for net5.0
and so on all the way back to .netcoreapp1.0
. So for each of these target frameworks, the Framework with version minimum bound symbol will be defined.
DocumentationFile
The DocumentationFile
property lets you specify a file name for the XML file that contains the documentation for your library. For IntelliSense to function correctly with your documentation, the file name must be the same as the assembly name and must be in the same directory as the assembly. If you don't specify this property but you do set GenerateDocumentationFile to true
, the name of the documentation file defaults to the name of your assembly but with an .xml file extension. For this reason, it's often easier to omit this property and use the GenerateDocumentationFile property instead.
If you specify this property but you set GenerateDocumentationFile to false
, the compiler does not generate a documentation file. If you specify this property and omit the GenerateDocumentationFile property, the compiler does generate a documentation file.
<PropertyGroup>
<DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>
EmbeddedResourceUseDependentUponConvention
The EmbeddedResourceUseDependentUponConvention
property defines whether resource manifest file names are generated from type information in source files that are co-located 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. 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 project that targets .NET Core 3.0 or a later version, 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>
EnablePreviewFeatures
The EnablePreviewFeatures
property defines whether your project depends on any APIs or assemblies that are decorated with the RequiresPreviewFeaturesAttribute attribute. This attribute is used to signify that an API or assembly uses features that are considered to be in preview for the SDK version you're using. Preview features are not supported and may be removed in a future version. To enable the use of preview features, set the property to True
.
<PropertyGroup>
<EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>
When a project contains this property set to True
, the following assembly-level attribute is added to the AssemblyInfo.cs file:
[assembly: RequiresPreviewFeatures]
An analyzer warns if this attribute is present on dependencies for projects where EnablePreviewFeatures
is not set to True
.
Library authors who intend to ship preview assemblies should set this property to True
. If an assembly needs to ship with a mixture of preview and non-preview APIs, see the GenerateRequiresPreviewFeaturesAttribute section below.
EnableWindowsTargeting
Set the EnableWindowsTargeting
property to true
to build Windows apps (for example, Windows Forms or Windows Presentation Foundation apps) on a non-Windows platform. If you don't set this property to true
, you'll get build warning NETSDK1100. This error occurs because targeting and runtime packs aren't automatically downloaded on platforms that aren't supported. By setting this property, those packs are downloaded when cross-targeting.
Note
This property is currently recommended to allow development on non-Windows platforms. But when the application is ready to be released, it should be built on Windows. When building on a non-Windows platform, the output may not be the same as when building on Windows. In particular, the executable is not marked as a Windows application (which means that it will always launch a console window) and won't have an icon embedded.
<PropertyGroup>
<EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>
GenerateDocumentationFile
The GenerateDocumentationFile
property controls whether the compiler generates an XML documentation file for your library. If you set this property to true
and you don't specify a file name via the DocumentationFile property, the generated XML file is placed in the same output directory as your assembly and has the same file name (but with an .xml extension).
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
For more information about generating documentation from code comments, see XML documentation comments (C#), Document your code with XML (Visual Basic), or Document your code with XML (F#).
GenerateRequiresPreviewFeaturesAttribute
The GenerateRequiresPreviewFeaturesAttribute
property is closely related to the EnablePreviewFeatures property. If your library uses preview features but you don't want the entire assembly to be marked with the RequiresPreviewFeaturesAttribute attribute, which would require any consumers to enable preview features, set this property to False
.
<PropertyGroup>
<EnablePreviewFeatures>True</EnablePreviewFeatures>
<GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>
Important
If you set the GenerateRequiresPreviewFeaturesAttribute
property to False
, you must be certain to decorate all public APIs that rely on preview features with RequiresPreviewFeaturesAttribute.
OptimizeImplicitlyTriggeredBuild
To speed up the build time, builds that are implicitly triggered by Visual Studio skip code analysis, including nullable analysis. Visual Studio triggers an implicit build when you run tests, for example. However, implicit builds are optimized only when TreatWarningsAsErrors
is not true
. If you have TreatWarningsAsErrors
set to true
but you still want implicitly triggered builds to be optimized, you can set OptimizeImplicitlyTriggeredBuild
to True
. To turn off build optimization for implicitly triggered builds, set OptimizeImplicitlyTriggeredBuild
to False
.
<PropertyGroup>
<OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>
DisableRuntimeMarshalling
The DisableRuntimeMarshalling
property enables you to specify that you would like to disable runtime marshalling support for your project. If this property is set to true
, then the DisableRuntimeMarshallingAttribute is added to the assembly and any P/Invokes or delegate-based interop will follow the rules for disabled runtime marshalling.
<PropertyGroup>
<DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</PropertyGroup>
Default item inclusion properties
The following MSBuild properties are documented in this section:
- DefaultItemExcludesInProjectFolder
- DefaultItemExcludes
- EnableDefaultCompileItems
- EnableDefaultEmbeddedResourceItems
- EnableDefaultItems
- EnableDefaultNoneItems
For more information, see Default includes and excludes.
DefaultItemExcludes
Use the DefaultItemExcludes
property to define glob patterns for files and folders that should be excluded from the include, exclude, and remove globs. By default, the ./bin and ./obj folders are excluded from the glob patterns.
<PropertyGroup>
<DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>
DefaultItemExcludesInProjectFolder
Use the DefaultItemExcludesInProjectFolder
property to define glob patterns for files and folders in the project folder that should be excluded from the include, exclude, and remove globs. By default, folders that start with a period (.
), such as .git and .vs, are excluded from the glob patterns.
This property is very similar to the DefaultItemExcludes
property, except that it only considers files and folders in the project folder. When a glob pattern would unintentionally match items outside the project folder with a relative path, use the DefaultItemExcludesInProjectFolder
property instead of the DefaultItemExcludes
property.
<PropertyGroup>
<DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</PropertyGroup>
EnableDefaultItems
The EnableDefaultItems
property controls whether compile items, embedded resource items, and None
items are implicitly included in the project. The default value is true
. Set the EnableDefaultItems
property to false
to disable all implicit file inclusion.
<PropertyGroup>
<EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>
EnableDefaultCompileItems
The EnableDefaultCompileItems
property controls whether compile items are implicitly included in the project. The default value is true
. Set the EnableDefaultCompileItems
property to false
to disable implicit inclusion of *.cs and other language-extension files.
<PropertyGroup>
<EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>
EnableDefaultEmbeddedResourceItems
The EnableDefaultEmbeddedResourceItems
property controls whether embedded resource items are implicitly included in the project. The default value is true
. Set the EnableDefaultEmbeddedResourceItems
property to false
to disable implicit inclusion of embedded resource files.
<PropertyGroup>
<EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>
EnableDefaultNoneItems
The EnableDefaultNoneItems
property controls whether None
items (files that have no role in the build process) are implicitly included in the project. The default value is true
. Set the EnableDefaultNoneItems
property to false
to disable implicit inclusion of None
items.
<PropertyGroup>
<EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>
Code analysis properties
The following MSBuild properties are documented in this section:
- AnalysisLevel
- AnalysisLevel<Category>
- AnalysisMode
- AnalysisMode<Category>
- CodeAnalysisTreatWarningsAsErrors
- EnableNETAnalyzers
- EnforceCodeStyleInBuild
- _SkipUpgradeNetAnalyzersNuGetWarning
AnalysisLevel
The AnalysisLevel
property lets you specify a set of code analyzers to run according to a .NET release. Each .NET release, starting in .NET 5, has a set of code analysis rules. Of that set, the rules that are enabled by default for that release will analyze your code. For example, if you upgrade to .NET 8 but don't want the default set of code analysis rules to change, set AnalysisLevel
to 7
.
<PropertyGroup>
<AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>
Optionally, starting in .NET 6, you can specify a compound value for this property that also specifies how aggressively to enable rules. Compound values take the form <version>-<mode>
, where the <mode>
value is one of the AnalysisMode values. The following example uses the preview version of code analyzers, and enables the recommended set of rules.
<PropertyGroup>
<AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>
Default value:
- If your project targets .NET 5 or later, or if you've added the AnalysisMode property, the default value is
latest
. - Otherwise, this property is omitted unless you explicitly add it to the project file.
The following table shows the values you can specify.
Value | Meaning |
---|---|
latest |
The latest code analyzers that have been released are used. This is the default. |
latest-<mode> |
The latest code analyzers that have been released are used. The <mode> value determines which rules are enabled. |
preview |
The latest code analyzers are used, even if they are in preview. |
preview-<mode> |
The latest code analyzers are used, even if they are in preview. The <mode> value determines which rules are enabled. |
8.0 |
The set of rules that was available for the .NET 8 release is used, even if newer rules are available. |
8.0-<mode> |
The set of rules that was available for the .NET 8 release is used, even if newer rules are available. The <mode> value determines which rules are enabled. |
8 |
The set of rules that was available for the .NET 8 release is used, even if newer rules are available. |
8-<mode> |
The set of rules that was available for the .NET 8 release is used, even if newer rules are available. The <mode> value determines which rules are enabled. |
7.0 |
The set of rules that was available for the .NET 7 release is used, even if newer rules are available. |
7.0-<mode> |
The set of rules that was available for the .NET 7 release is used, even if newer rules are available. The <mode> value determines which rules are enabled. |
7 |
The set of rules that was available for the .NET 7 release is used, even if newer rules are available. |
7-<mode> |
The set of rules that was available for the .NET 7 release is used, even if newer rules are available. The <mode> value determines which rules are enabled. |
6.0 |
The set of rules that was available for the .NET 6 release is used, even if newer rules are available. |
6.0-<mode> |
The set of rules that was available for the .NET 6 release is used, even if newer rules are available. The <mode> value determines which rules are enabled. |
6 |
The set of rules that was available for the .NET 6 release is used, even if newer rules are available. |
6-<mode> |
The set of rules that was available for the .NET 6 release is used, even if newer rules are available. The <mode> value determines which rules are enabled. |
5.0 |
The set of rules that was available for the .NET 5 release is used, even if newer rules are available. |
5.0-<mode> |
The set of rules that was available for the .NET 5 release is used, even if newer rules are available. The <mode> value determines which rules are enabled. |
5 |
The set of rules that was available for the .NET 5 release is used, even if newer rules are available. |
5-<mode> |
The set of rules that was available for the .NET 5 release is used, even if newer rules are available. The <mode> value determines which rules are enabled. |
Note
- Starting in .NET 6, if you set EnforceCodeStyleInBuild to
true
, this property affects code-style (IDEXXXX) rules (in addition to code-quality rules). - If you set a compound value for
AnalysisLevel
, you don't need to specify an AnalysisMode. However, if you do,AnalysisLevel
takes precedence overAnalysisMode
. - This property has no effect on code analysis in projects that don't reference a project SDK, for example, legacy .NET Framework projects that reference the Microsoft.CodeAnalysis.NetAnalyzers NuGet package.
AnalysisLevel<Category>
This property is the same as AnalysisLevel, except that it only applies to a specific category of code-analysis rules. This property allows you to use a different version of code analyzers for a specific category, or to enable or disable rules at a different level to the other rule categories. If you omit this property for a particular category of rules, it defaults to the AnalysisLevel value. The available values are the same as those for AnalysisLevel.
<PropertyGroup>
<AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>
<PropertyGroup>
<AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>
The following table lists the property name for each rule category.
Property name | Rule category |
---|---|
<AnalysisLevelDesign> |
Design rules |
<AnalysisLevelDocumentation> |
Documentation rules |
<AnalysisLevelGlobalization> |
Globalization rules |
<AnalysisLevelInteroperability> |
Portability and interoperability rules |
<AnalysisLevelMaintainability> |
Maintainability rules |
<AnalysisLevelNaming> |
Naming rules |
<AnalysisLevelPerformance> |
Performance rules |
<AnalysisLevelSingleFile> |
Single-file application rules |
<AnalysisLevelReliability> |
Reliability rules |
<AnalysisLevelSecurity> |
Security rules |
<AnalysisLevelStyle> |
Code-style (IDEXXXX) rules |
<AnalysisLevelUsage> |
Usage rules |
AnalysisMode
The .NET SDK ships with all of the "CA" code quality rules. By default, only some rules are enabled as build warnings in each .NET release. The AnalysisMode
property lets you customize the set of rules that's enabled by default. You can either switch to a more aggressive analysis mode where you can opt out of rules individually, or a more conservative analysis mode where you can opt in to specific rules. For example, if you want to enable all rules as build warnings, set the value to All
.
<PropertyGroup>
<AnalysisMode>All</AnalysisMode>
</PropertyGroup>
The following table shows the available option values. They're listed in increasing order of the number of rules they enable.
Value | Description |
---|---|
None |
All rules are disabled. You can selectively opt in to individual rules to enable them. |
Default |
Default mode, where certain rules are enabled as build warnings, certain rules are enabled as Visual Studio IDE suggestions, and the remainder are disabled. |
Minimum |
More aggressive mode than Default mode. Certain suggestions that are highly recommended for build enforcement are enabled as build warnings. To see which rules this includes, inspect the %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig file. |
Recommended |
More aggressive mode than Minimum mode, where more rules are enabled as build warnings. To see which rules this includes, inspect the %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig file. |
All |
All rules are enabled as build warnings*. You can selectively opt out of individual rules to disable them. * The following rules are not enabled by setting AnalysisMode to All or by setting AnalysisLevel to latest-all : CA1017, CA1045, CA1005, CA1014, CA1060, CA1021, and the code metrics analyzer rules (CA1501, CA1502, CA1505, CA1506, and CA1509). These legacy rules might be deprecated in a future version. However, you can still enable them individually using a dotnet_diagnostic.CAxxxx.severity = <severity> entry. |
Note
- Starting in .NET 6, if you set EnforceCodeStyleInBuild to
true
, this property affects code-style (IDEXXXX) rules (in addition to code-quality rules). - If you use a compound value for AnalysisLevel, for example,
<AnalysisLevel>8-recommended</AnalysisLevel>
, you can omit this property entirely. However, if you specify both properties,AnalysisLevel
takes precedence overAnalysisMode
. - This property has no effect on code analysis in projects that don't reference a project SDK, for example, legacy .NET Framework projects that reference the Microsoft.CodeAnalysis.NetAnalyzers NuGet package.
AnalysisMode<Category>
This property is the same as AnalysisMode, except that it only applies to a specific category of code-analysis rules. This property allows you to enable or disable rules at a different level to the other rule categories. If you omit this property for a particular category of rules, it defaults to the AnalysisMode value. The available values are the same as those for AnalysisMode.
<PropertyGroup>
<AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>
The following table lists the property name for each rule category.
Property name | Rule category |
---|---|
<AnalysisModeDesign> |
Design rules |
<AnalysisModeDocumentation> |
Documentation rules |
<AnalysisModeGlobalization> |
Globalization rules |
<AnalysisModeInteroperability> |
Portability and interoperability rules |
<AnalysisModeMaintainability> |
Maintainability rules |
<AnalysisModeNaming> |
Naming rules |
<AnalysisModePerformance> |
Performance rules |
<AnalysisModeSingleFile> |
Single-file application rules |
<AnalysisModeReliability> |
Reliability rules |
<AnalysisModeSecurity> |
Security rules |
<AnalysisModeStyle> |
Code-style (IDEXXXX) rules |
<AnalysisModeUsage> |
Usage rules |
CodeAnalysisTreatWarningsAsErrors
The CodeAnalysisTreatWarningsAsErrors
property lets you configure whether code quality analysis warnings (CAxxxx) should be treated as warnings and break the build. If you use the -warnaserror
flag when you build your projects, .NET code quality analysis warnings are also treated as errors. If you do not want code quality analysis warnings to be treated as errors, you can set the CodeAnalysisTreatWarningsAsErrors
MSBuild property to false
in your project file.
<PropertyGroup>
<CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>
EnableNETAnalyzers
.NET code quality analysis is enabled, by default, for projects that target .NET 5 or a later version. If you're developing using the .NET 5+ SDK, you can enable .NET code analysis for SDK-style projects that target earlier versions of .NET by setting the EnableNETAnalyzers
property to true
. To disable code analysis in any project, set this property to false
.
<PropertyGroup>
<EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>
Note
This property applies specifically to the built-in analyzers in the .NET 5+ SDK. It should not be used when you install a NuGet code analysis package.
EnforceCodeStyleInBuild
.NET code style analysis is disabled, by default, on build for all .NET projects. You can enable code style analysis for .NET projects by setting the EnforceCodeStyleInBuild
property to true
.
<PropertyGroup>
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>
All code style rules that are configured to be warnings or errors will execute on build and report violations.
_SkipUpgradeNetAnalyzersNuGetWarning
The _SkipUpgradeNetAnalyzersNuGetWarning
property lets you configure whether you receive a warning if you're using code analyzers from a NuGet package that's out-of-date when compared with the code analyzers in the latest .NET SDK. The warning looks similar to:
The .NET SDK has newer analyzers with version '6.0.0' than what version '5.0.3' of 'Microsoft.CodeAnalysis.NetAnalyzers' package provides. Update or remove this package reference.
To remove this warning and continue to use the version of code analyzers in the NuGet package, set _SkipUpgradeNetAnalyzersNuGetWarning
to true
in your project file.
<PropertyGroup>
<_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>
Runtime configuration properties
You can configure some runtime behaviors by specifying MSBuild properties in the project file of the app. For information about other ways of configuring runtime behavior, see Runtime configuration settings.
- AutoreleasePoolSupport
- ConcurrentGarbageCollection
- InvariantGlobalization
- PredefinedCulturesOnly
- RetainVMGarbageCollection
- ServerGarbageCollection
- ThreadPoolMaxThreads
- ThreadPoolMinThreads
- TieredCompilation
- TieredCompilationQuickJit
- TieredCompilationQuickJitForLoops
- TieredPGO
- UseWindowsThreadPool
AutoreleasePoolSupport
The AutoreleasePoolSupport
property configures whether each managed thread receives an implicit NSAutoreleasePool when running on a supported macOS platform. For more information, see AutoreleasePool
for managed threads.
<PropertyGroup>
<AutoreleasePoolSupport>true</AutoreleasePoolSupport>
</PropertyGroup>
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 Background GC.
<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>
PredefinedCulturesOnly
In .NET 6 and later versions, the PredefinedCulturesOnly
property configures whether apps can create cultures other than the invariant culture when globalization-invariant mode is enabled. The default is true
. Set the value to false
to allow creation of any new culture in globalization-invariant mode.
<PropertyGroup>
<PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>
For more information, see Culture creation and case mapping in globalization-invariant mode.
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 Retain VM.
<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 Workstation vs. server.
<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>
TieredPGO
The TieredPGO
property controls whether dynamic or tiered profile-guided optimization (PGO) is enabled. Set the value to true
to enable tiered PGO. For more information, see Profile-guided optimization.
<PropertyGroup>
<TieredPGO>true</TieredPGO>
</PropertyGroup>
UseWindowsThreadPool
The UseWindowsThreadPool
property configures whether thread pool thread management is delegated to the Windows thread pool (Windows only). The default value is false
, in which case the .NET thread pool is used. For more information, see Windows thread pool.
<PropertyGroup>
<UseWindowsThreadPool>true</UseWindowsThreadPool>
</PropertyGroup>
Reference-related properties
The following MSBuild properties are documented in this section:
- AssetTargetFallback
- DisableImplicitFrameworkReferences
- DisableTransitiveFrameworkReferenceDownloads
- DisableTransitiveProjectReferences
- ManagePackageVersionsCentrally
- Restore-related properties
- UseMauiEssentials
- ValidateExecutableReferencesMatchSelfContained
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
. This property replaces the deprecated property PackageTargetFallback
.
You can set the AssetTargetFallback
property to one or more target framework versions.
<PropertyGroup>
<AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>
DisableImplicitFrameworkReferences
The DisableImplicitFrameworkReferences
property controls implicit FrameworkReference
items when targeting .NET Core 3.0 and later versions. When targeting .NET Core 2.1 or .NET Standard 2.0 and earlier versions, it controls implicit PackageReference items to packages in a metapackage. (A metapackage is a framework-based package that consists only of dependencies on other packages.) This property also controls implicit references such as System
and System.Core
when targeting .NET Framework.
Set this property to true
to disable implicit FrameworkReference or PackageReference items. If you set this property to true
, you can add explicit references to just the frameworks or packages you need.
<PropertyGroup>
<DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>
DisableTransitiveFrameworkReferenceDownloads
Set the DisableTransitiveFrameworkReferenceDownloads
property to true
to avoid downloading extra runtime and targeting packs that aren't directly referenced by your project.
<PropertyGroup>
<DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>
DisableTransitiveProjectReferences
The DisableTransitiveProjectReferences
property controls implicit project references. Set this property to true
to disable implicit ProjectReference
items. Disabling implicit project references results in non-transitive behavior similar to the legacy project system.
When this property is true
, it has a similar effect to that of setting PrivateAssets="All"
on all of the dependencies of the depended-upon project.
If you set this property to true
, you can add explicit references to just the projects you need.
<PropertyGroup>
<DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>
ManagePackageVersionsCentrally
The ManagePackageVersionsCentrally
property was introduced in .NET 7. By setting it to true
in a Directory.Packages.props file in the root of your repository, you can manage common dependencies in your projects from one location. Add versions for common package dependencies using PackageVersion
items in the Directory.Packages.props file. Then, in the individual project files, you can omit Version
attributes from any PackageReference
items that refer to centrally managed packages.
Example Directory.Packages.props file:
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
<PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>
Individual project file:
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>
For more information, see central package management (CPM).
Restore-related 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>
UseMauiEssentials
Set the UseMauiEssentials
property to true
to declare an explicit reference to a project or package that depends on MAUI Essentials. This setting ensures that your project pulls in the correct known framework reference for MAUI Essentials. If your project references a project that uses MAUI Essentials but you don't set this property to true
, you might encounter build warning NETSDK1186
.
<PropertyGroup>
<UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>
ValidateExecutableReferencesMatchSelfContained
The ValidateExecutableReferencesMatchSelfContained
property can be used to disable errors related to executable project references. If .NET detects that a self-contained executable project references a framework-dependent executable project, or vice versa, it generates errors NETSDK1150 and NETSDK1151, respectively. To avoid these errors when the reference is intentional, set the ValidateExecutableReferencesMatchSelfContained
property to false
.
<PropertyGroup>
<ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>
WindowsSdkPackageVersion
The WindowsSdkPackageVersion
property can be used to override the version of the Windows SDK targeting package. This property was introduced in .NET 5, and replaces the use of the FrameworkReference
item for this purpose.
<PropertyGroup>
<WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>
Note
We don't recommend overriding the Windows SDK version, because the Windows SDK targeting packages are included with the .NET 5+ SDK. Instead, to reference the latest Windows SDK package, update your version of the .NET SDK. This property should only be used in rare cases such as using preview packages or needing to override the version of C#/WinRT.
Run-related properties
The following properties are used for launching an app with the dotnet run
command:
RunArguments
The RunArguments
property defines the arguments that are passed to the app when it's run.
<PropertyGroup>
<RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>
Tip
You can specify additional arguments to be passed to the app by using the --
option for dotnet run
.
RunWorkingDirectory
The RunWorkingDirectory
property defines the working directory for the application process to be started in. It can be an absolute path or a path that's relative to the project directory. If you don't specify a directory, OutDir
is used as the working directory.
<PropertyGroup>
<RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>
Test project–related properties
The following MSBuild properties are documented in this section:
- IsTestProject
- IsTestingPlatformApplication
- Enable[NugetPackageNameWithoutDots]
- EnableAspireTesting
- EnablePlaywright
- EnableMSTestRunner
- EnableNUnitRunner
- GenerateTestingPlatformEntryPoint
- TestingPlatformCaptureOutput
- TestingPlatformCommandLineArguments
- TestingPlatformDotnetTestSupport
- TestingPlatformShowTestsFailure
- TestingExtensionsProfile
- UseVSTest
IsTestProject
The IsTestProject
property signifies that a project is a test project. When this property is set to true
, validation to check if the project references a self-contained executable is disabled. That's because test projects have an OutputType
of Exe
but usually call APIs in a referenced executable rather than trying to run. In addition, if a project references a project where IsTestProject
is set to true
, the test project isn't validated as an executable reference.
This property is mainly needed for the dotnet test
scenario and has no impact when using vstest.console.exe.
Note
If your project specifies the MSTest SDK, you don't need to set this property. It's set automatically. Similarly, this property is set automatically for projects that reference the Microsoft.NET.Test.Sdk NuGet package linked to VSTest.
IsTestingPlatformApplication
When your project references the Microsoft.Testing.Platform.MSBuild package, setting IsTestingPlatformApplication
to true
(which is also the default value if not specified) does the following:
- Generates the entry point to the test project.
- Generates the configuration file.
- Detects the extensions.
Setting the property to false
disables the transitive dependency to the package. A transitive dependency is when a project that references another project that references a given package behaves as if it references the package. You'd typically set this property to false
in a non-test project that references a test project. For more information, see error CS8892.
If your test project references MSTest, NUnit, or xUnit, this property is set to the same value as EnableMSTestRunner, EnableNUnitRunner, or UseMicrosoftTestingPlatformRunner
(for xUnit).
Enable[NugetPackageNameWithoutDots]
Use a property with the pattern Enable[NugetPackageNameWithoutDots]
to enable or disable Microsoft.Testing.Platform extensions.
For example, to enable the crash dump extension (NuGet package Microsoft.Testing.Extensions.CrashDump), set the EnableMicrosoftTestingExtensionsCrashDump
to true
.
For more information, see Enable or disable extensions.
EnableAspireTesting
When you use the MSTest project SDK, you can use the EnableAspireTesting
property to bring in all the dependencies and default using
directives you need for testing with Aspire
and MSTest
. This property is available in MSTest 3.4 and later versions.
For more information, see Test with .NET Aspire.
EnablePlaywright
When you use the MSTest project SDK, you can use the EnablePlaywright
property to bring in all the dependencies and default using
directives you need for testing with Playwright
and MSTest
.This property is available in MSTest 3.4 and later versions.
For more information, see Playwright.
EnableMSTestRunner
The EnableMSTestRunner
property enables or disables the use of the MSTest runner. The MSTest runner is a lightweight and portable alternative to VSTest. This property is available in MSTest 3.2 and later versions.
Note
If your project specifies the MSTest SDK, you don't need to set this property. It's set automatically.
EnableNUnitRunner
The EnableNUnitRunner
property enables or disables the use of the NUnit runner. The NUnit runner is a lightweight and portable alternative to VSTest. This property is available in NUnit3TestAdapter in version 5.0 and later.
GenerateTestingPlatformEntryPoint
Setting the GenerateTestingPlatformEntryPoint
property to false
disables the automatic generation of the program entry point in an MSTest, NUnit, or xUnit test project. You might want to set this property to false
when you manually define an entry point, or when you reference a test project from an executable that also has an entry point.
For more information, see error CS8892.
To control the generation of the entry point in a VSTest project, use the GenerateProgramFile
property.
TestingPlatformCaptureOutput
The TestingPlatformCaptureOutput
property controls whether all console output that a test executable writes is captured and hidden from the user when you use dotnet test
to run Microsoft.Testing.Platform
tests. By default, the console output is hidden. This output includes the banner, version information, and formatted test information. Set this property to false
to show this information together with MSBuild output.
For more information, see Show complete platform output.
TestingPlatformCommandLineArguments
The TestingPlatformCaptureOutput
property lets you specify command-line arguments to the test app when you use dotnet test
to run Microsoft.Testing.Platform
tests. The following project file snippet shows an example.
<PropertyGroup>
...
<TestingPlatformCommandLineArguments>--minimum-expected-tests 10</TestingPlatformCommandLineArguments>
</PropertyGroup>
TestingPlatformDotnetTestSupport
The TestingPlatformDotnetTestSupport
property lets you specify whether VSTest is used when you use dotnet test
to run tests. If you set this property to true
, VSTest is disabled and all Microsoft.Testing.Platform
tests are run directly.
If you have a solution that contains VSTest test projects as well as MSTest, NUnit, or XUnit projects, you should make one call per mode (that is, dotnet test
won't run tests from both VSTest and the newer platforms in one call).
TestingPlatformShowTestsFailure
The TestingPlatformShowTestsFailure
property lets you control whether a single failure or all errors in a failed test are reported when you use dotnet test
to run tests. By default, test failures are summarized into a .log file, and a single failure per test project is reported to MSBuild. To show errors per failed test, set this property to true
in your project file.
TestingExtensionsProfile
When you use the MSTest project SDK, the TestingExtensionsProfile
property lets you select a profile to use. The following table shows the allowable values.
Value | Description |
---|---|
Default |
Enables the recommended extensions for this version of MSTest.SDK. |
None |
No extensions are enabled. |
AllMicrosoft |
Enable all extensions shipped by Microsoft (including extensions with a restrictive license). |
For more information, see MSTest runner profile.
UseVSTest
Set the UseVSTest
property to true
to switch from the MSTest runner to the VSTest runner when using the MSTest project SDK.
Hosting-related properties
The following MSBuild properties are documented in this section:
AppHostDotNetSearch
The AppHostDotNetSearch
property configures how the native executable produced for an application will search for a .NET installation. This property only impacts the executable produced on publish, not build.
<PropertyGroup>
<AppHostDotNetSearch>Global</AppHostDotNetSearch>
</PropertyGroup>
The following table lists valid values. You can specify multiple values, separated by semi-colons.
Value | Meaning |
---|---|
AppLocal |
App executable's folder |
AppRelative |
Path relative to the app executable as specified by AppHostRelativeDotNet |
EnvironmentVariables |
Value of DOTNET_ROOT[_<arch>] environment variables |
Global |
Registered and default global install locations |
This property was introduced in .NET 9.
AppHostRelativeDotNet
The AppHostRelativeDotNet
property allows specifying a relative path for the app executable to look for the .NET installation when it's configured to do so. Setting the AppHostRelativeDotNet
property implies that AppHostDotNetSearch
is AppRelative
. This property only impacts the executable produced on publish, not build.
<PropertyGroup>
<AppHostRelativeDotNet>./relative/path/to/runtime</AppHostRelativeDotNet>
</PropertyGroup>
This property was introduced in .NET 9.
EnableComHosting
The EnableComHosting
property indicates that an assembly provides a COM server. Setting the EnableComHosting
to true
also implies that EnableDynamicLoading is true
.
<PropertyGroup>
<EnableComHosting>True</EnableComHosting>
</PropertyGroup>
For more information, see Expose .NET components to COM.
EnableDynamicLoading
The EnableDynamicLoading
property indicates that an assembly is a dynamically loaded component. The component could be a COM library or a non-COM library that can be used from a native host or used as a plugin. Setting this property to true
has the following effects:
- A .runtimeconfig.json file is generated.
- RollForward is set to
LatestMinor
. - NuGet references are copied locally.
<PropertyGroup>
<EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>
Generated file properties
The following properties concern code in generated files:
DisableImplicitNamespaceImports
The DisableImplicitNamespaceImports
property can be used to disable implicit namespace imports in Visual Basic projects that target .NET 6 or a later version. Implicit namespaces are the default namespaces that are imported globally in a Visual Basic project. Set this property to true
to disable implicit namespace imports.
<PropertyGroup>
<DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>
ImplicitUsings
The ImplicitUsings
property can be used to enable and disable implicit global using
directives in C# projects that target .NET 6 or a later version and C# 10 or a later version. When the feature is enabled, the .NET SDK adds global using
directives for a set of default namespaces based on the type of project SDK. Set this property to true
or enable
to enable implicit global using
directives. To disable implicit global using
directives, remove the property or set it to false
or disable
.
<PropertyGroup>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
Note
The templates for new C# projects that target .NET 6 or later have ImplicitUsings
set to enable
by default.
To define an explicit global using
directive, add a Using item.
Items
MSBuild items are inputs into the build system. Items are specified according to their type, which is the element name. For example, Compile
and Reference
are two common item types. The following additional item types are made available by the .NET SDK:
You can use any of the standard item attributes, for example, Include
and Update
, on these items. Use Include
to add a new item, and use Update
to modify an existing item. For example, Update
is often used to modify an item that has implicitly been added by the .NET SDK.
AssemblyMetadata
The AssemblyMetadata
item specifies a key-value pair AssemblyMetadataAttribute assembly attribute. The Include
metadata becomes the key, and the Value
metadata becomes the value.
<ItemGroup>
<AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>
InternalsVisibleTo
The InternalsVisibleTo
item generates an InternalsVisibleToAttribute assembly attribute for the specified friend assembly.
<ItemGroup>
<InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>
If the friend assembly is signed, you can specify an optional Key
metadata to specify its full public key. If you don't specify Key
metadata and a $(PublicKey)
is available, that key is used. Otherwise, no public key is added to the attribute.
FrameworkReference
The FrameworkReference
item defines a reference to a .NET shared framework.
The Include
attribute specifies the framework ID.
The project file snippet in the following example references the Microsoft.AspNetCore.App shared framework.
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
PackageReference
The PackageReference
item defines a reference to a NuGet package.
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.
The project file snippet in the following example references the System.Runtime package.
<ItemGroup>
<PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>
You can also control dependency assets using metadata such as PrivateAssets
.
<ItemGroup>
<PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
<PrivateAssets>all</PrivateAssets>
</PackageReference>
</ItemGroup>
For more information, see Package references in project files.
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>
For more information, see Trimming options.
Using
The Using
item lets you globally include a namespace across your C# project, such that you don't have to add a using
directive for the namespace at the top of your source files. This item is similar to the Import
item that can be used for the same purpose in Visual Basic projects. This property is available starting in .NET 6.
<ItemGroup>
<Using Include="My.Awesome.Namespace" />
</ItemGroup>
You can also use the Using
item to define global using <alias>
and using static <type>
directives.
<ItemGroup>
<Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>
For example:
<Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" />
emitsglobal using Results = global::Microsoft.AspNetCore.Http.Results;
<Using Include="Microsoft.AspNetCore.Http.Results" Static="True" />
emitsglobal using static global::Microsoft.AspNetCore.Http.Results;
For more information, see aliased using
directives and using static <type>
directives.
Item metadata
In addition to the standard MSBuild item attributes, the following item metadata tags are made available by the .NET SDK:
CopyToPublishDirectory
The CopyToPublishDirectory
metadata on an MSBuild item controls when the item is copied to the publish directory. Allowable values are PreserveNewest
, which only copies the item if it has changed, Always
, which always copies the item, and Never
, which never copies the item. From a performance standpoint, PreserveNewest
is preferable because it enables an incremental build.
<ItemGroup>
<None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>
LinkBase
For an item that's outside of the project directory and its subdirectories, the publish target uses the item's Link metadata to determine where to copy the item to. Link
also determines how items outside of the project tree are displayed in the Solution Explorer window of Visual Studio.
If Link
is not specified for an item that's outside of the project cone, it defaults to %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension)
. LinkBase
lets you specify a sensible base folder for items outside of the project cone. The folder hierarchy under the base folder is preserved via RecursiveDir
. If LinkBase
is not specified, it's omitted from the Link
path.
<ItemGroup>
<Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>
The following image shows how a file that's included via the previous item Include
glob displays in Solution Explorer.