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.

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>netcoreapp3.1</TargetFramework>
</PropertyGroup>


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>


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 info generation properties

GenerateAssemblyCompanyAttribute

This property controls whether or not the Company property generates the AssemblyCompanyAttribute for the assembly. The default value is true.

<PropertyGroup>
<GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
</PropertyGroup>


GenerateAssemblyConfigurationAttribute

This property controls whether or not the Configuration property generates the AssemblyConfigurationAttribute for the assembly. The default value is true.

<PropertyGroup>
<GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
</PropertyGroup>


This property controls whether or not the Copyright property generates the AssemblyCopyrightAttribute for the assembly. The default value is true.

<PropertyGroup>
</PropertyGroup>


GenerateAssemblyDescriptionAttribute

This property controls whether or not the Description property generates the AssemblyDescriptionAttribute for the assembly. The default value is true.

<PropertyGroup>
<GenerateAssemblyDescriptionAttribute>false</GenerateAssemblyDescriptionAttribute>
</PropertyGroup>


GenerateAssemblyFileVersionAttribute

This property controls whether or not the FileVersion property generates the AssemblyFileVersionAttribute for the assembly. The default value is true.

<PropertyGroup>
<GenerateAssemblyFileVersionAttribute>false</GenerateAssemblyFileVersionAttribute>
</PropertyGroup>


GenerateAssemblyInfo

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, project properties are transformed into AssemblyInfo attributes. The following table lists the project properties that generate the attributes, and the properties that can disable that generation:

Property Attribute Property to disable
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

• AssemblyVersion and FileVersion default to the value of $(Version) without the suffix. For example, if $(Version) is 1.2.3-beta.4, then the value would be 1.2.3.
• InformationalVersion defaults to the value of $(Version). • If the $(SourceRevisionId) property is present, it's appended to InformationalVersion. You can disable this behavior using IncludeSourceRevisionInInformationalVersion.
• Copyright and Description properties are also used for NuGet metadata.
• Configuration, which defaults to Debug, is shared with all MSBuild targets. You can set it via the --configuration option of dotnet commands, for example, dotnet pack.
• Some of the properties are used when creating a NuGet package. For more information, see Package properties.

Migrating from .NET Framework

.NET Framework project templates create a code file with these assembly info attributes set. The file is typically located at .\Properties\AssemblyInfo.cs or .\Properties\AssemblyInfo.vb. SDK-style projects generate this file for you based on the project settings. You can't have both. When porting your code to .NET 5 (and .NET Core 3.1) or later, do one of the following:

• Disable the generation of the temporary code file that contains the assembly info attributes by setting GenerateAssemblyInfo to false. This enables you to keep your AssemblyInfo file.
• Migrate the settings in the AssemblyInfo file to the project file, and delete the AssemblyInfo file.

GenerateAssemblyInformationalVersionAttribute

This property controls whether or not the InformationalVersion property generates the AssemblyInformationalVersionAttribute for the assembly. The default value is true.

<PropertyGroup>
<GenerateAssemblyInformationalVersionAttribute>false</GenerateAssemblyInformationalVersionAttribute>
</PropertyGroup>


GenerateAssemblyProductAttribute

This property controls whether or not the Product property generates the AssemblyProductAttribute for the assembly. The default value is true.

<PropertyGroup>
<GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
</PropertyGroup>


GenerateAssemblyTitleAttribute

This property controls whether or not the AssemblyTitle property generates the AssemblyTitleAttribute for the assembly. The default value is true.

<PropertyGroup>
<GenerateAssemblyTitleAttribute>false</GenerateAssemblyTitleAttribute>
</PropertyGroup>


GenerateAssemblyVersionAttribute

This property controls whether or not the AssemblyVersion property generates the AssemblyVersionAttribute for the assembly. The default value is true.

<PropertyGroup>
<GenerateAssemblyVersionAttribute>false</GenerateAssemblyVersionAttribute>
</PropertyGroup>


The 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>  GenerateNeutralResourcesLanguageAttribute This property controls whether or not the NeutralLanguage property generates the NeutralResourcesLanguageAttribute for the assembly. The default value is true. <PropertyGroup> <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute> </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>  The following MSBuild properties are documented in this section: 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.0 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.0 app and an RID of win10-x64, the output path changes from bin\Debug\net5.0\win10-x64 to bin\Debug\net5.0 with the following setting: <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 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>  Tip Alternatively, you can use dotnet publish to publish the class library. For more information, see dotnet publish. 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. 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>  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. 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 application deployment. The following MSBuild properties are documented in this section: 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 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. Default item inclusion properties The following MSBuild properties are documented in this section: 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>


DefaultExcludesInProjectFolder

Use the DefaultExcludesInProjectFolder 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 DefaultExcludesInProjectFolder property instead of the DefaultItemExcludes property.

<PropertyGroup>
<DefaultExcludesInProjectFolder>\$(DefaultExcludesInProjectFolder);**/myprefix*/**</DefaultExcludesInProjectFolder>
</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

The AnalysisLevel property lets you specify a code-analysis level. For example, if you want access to preview code analyzers, set AnalysisLevel to preview.

Default value:

• If your project targets .NET 5.0 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.
<PropertyGroup>
<AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>


The following table shows the available options.

Value Meaning
latest The latest code analyzers that have been released are used. This is the default.
preview The latest code analyzers are used, even if they are in preview.
5.0 The set of rules that was enabled for the .NET 5.0 release is used, even if newer rules are available.
5 The set of rules that was enabled for the .NET 5.0 release is used, even if newer rules are available.

Note

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

Starting with .NET 5.0, the .NET SDK ships with all of the "CA" code quality rules. By default, only some rules are enabled as build warnings. The AnalysisMode property lets you customize the set of rules that are enabled by default. You can either switch to a more aggressive (opt-out) analysis mode or a more conservative (opt-in) analysis mode. For example, if you want to enable all rules by default as build warnings, set the value to AllEnabledByDefault.

<PropertyGroup>
<AnalysisMode>AllEnabledByDefault</AnalysisMode>
</PropertyGroup>


The following table shows the available options.

Value Meaning
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.
AllEnabledByDefault Aggressive or opt-out mode, where all rules are enabled by default as build warnings. You can selectively opt out of individual rules to disable them.
AllDisabledByDefault Conservative or opt-in mode, where all rules are disabled by default. You can selectively opt into individual rules to enable them.

Note

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.

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.0 or later. 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

Note

This feature is currently experimental and may change between the .NET 5 and .NET 6 releases.

.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.

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 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 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>


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>


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

<PropertyGroup>
</PropertyGroup>


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

<PropertyGroup>
</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

The following MSBuild properties are documented in this section:

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 consist 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>


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>


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 is 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>


The following MSBuild properties are documented in this section:

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>


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. Setting this property to true has the following effects:

• A .runtimeconfig.json file is generated.
• Roll forward is set to LatestMinor.
• NuGet references are copied locally.
<PropertyGroup>
</PropertyGroup>


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.

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>


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>


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>
</ItemGroup>


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>

The following image shows how a file that's included via the previous item Include glob displays in Solution Explorer.