.NET SDK 项目的 MSBuild 引用

  • 项目

此页是对可用于配置 .NET 项目的 MSBuild 属性和项的引用。

注意

此页面正在运行中，未列出 .NET SDK 的所有有用的 MSBuild 属性。 有关通用 MSBuild 属性的列表，请参阅通用 MSBuild 属性。

框架属性

本节收录了以下 MSBuild 属性：

TargetFramework

TargetFramework 属性指定应用的目标框架版本。 有关有效的目标框架名字对象的列表，请参阅 SDK 样式项目中的目标框架。

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

有关详细信息，请参阅 SDK 样式项目中的目标框架。

TargetFrameworks

如果希望应用面向多个平台，请使用 TargetFrameworks 属性。 有关有效的目标框架名字对象的列表，请参阅 SDK 样式项目中的目标框架。

注意

如果指定了 TargetFramework（单数），则忽略此属性。

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

有关详细信息，请参阅 SDK 样式项目中的目标框架。

NetStandardImplicitPackageVersion

注意

此属性仅适用于使用 netstandard1.x 的项目。 它不适用于使用 netstandard2.x 的项目。

如果要指定低于元包版本的框架版本，请使用 NetStandardImplicitPackageVersion 属性。 以下示例中的项目文件以 netstandard1.3 为目标，但使用 NETStandard.Library 的 1.6.0 版本。

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

程序集特性属性

GenerateAssemblyInfo

GenerateAssemblyInfo 属性控制项目的 AssemblyInfo 特性生成。 默认值为 true。 使用 false 禁用文件生成：

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

GeneratedAssemblyInfoFile 设置控制生成的文件的名称。

当 GenerateAssemblyInfo 值为 true 时，与包相关的项目属性将转换为程序集特性。 下表列出了用于生成特性的项目属性。 还列出了可用于基于每个特性禁用该生成的属性，例如：

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
MSBuild 属性 程序集属性 要禁用特性生成的属性
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 和 FileVersion 默认采用 $(Version) 的值而不带后缀。 例如，如果 $(Version) 为 1.2.3-beta.4，则值将为 1.2.3。
  • InformationalVersion 默认是 $(Version) 的值。
  • 如果存在 $(SourceRevisionId) 属性，则该属性会附加到 InformationalVersion。 可以使用 IncludeSourceRevisionInInformationalVersion 禁用此行为。
  • Copyright 和 Description 属性也可用于 NuGet 元数据。
  • Configuration（默认值为 Debug）由所有 MSBuild 目标共享。 可以通过 dotnet 命令的 --configuration 选项对其进行设置，例如 dotnet pack。
  • 创建 NuGet 包时会使用某些属性。 有关详细信息，请参阅包属性。

从 .NET Framework 迁移

.NET Framework 项目模板会创建一个包含这些程序集信息属性集的代码文件。 该文件通常位于 .\Properties\AssemblyInfo.cs 或 .\Properties\AssemblyInfo.vb 。 SDK 样式项目基于项目设置为你生成此文件。 你不能同时具有这两者。 将代码移植到 .NET 5（或 .NET Core 3.1）或更高版本时，请执行以下操作之一：

  • 通过在项目文件中将 GenerateAssemblyInfo 设置为 false 来禁用包含程序集信息特性的临时代码文件的生成。 这使你可以保留 AssemblyInfo 文件。
  • 将 AssemblyInfo 文件中的设置迁移到项目文件，然后删除该 AssemblyInfo 文件。

GeneratedAssemblyInfoFile

GeneratedAssemblyInfoFile 属性定义生成的程序集信息文件的相对或绝对路径。 默认为 $(IntermediateOutputPath)（通常为 obj）目录中名为 [project-name].AssemblyInfo.[cs|vb] 的文件 。

<PropertyGroup>
  <GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>

包属性

可以指定 PackageId、PackageVersion、PackageIcon、Title 和 Description 等属性来描述通过项目创建的包。 若要了解这些属性和其他属性，请参阅包目标。

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

PackRelease

PackRelease 属性类似于 PublishRelease 属性，不同之处在于它更改了 dotnet pack 的默认行为。

<PropertyGroup>
  <PackRelease>true</PackRelease>
</PropertyGroup>

本节收录了以下 MSBuild 属性：

AppendTargetFrameworkToOutputPath

AppendTargetFrameworkToOutputPath 属性控制是否将目标框架名字对象 (TFM) 追加到输出路径（由 OutputPath 定义）。 .NET SDK 会自动将目标框架以及运行时标识符（如果有）追加到输出路径。 将 AppendTargetFrameworkToOutputPath 设置为 false 可防止将 TFM 追加到输出路径。 但是，如果输出路径中没有 TFM，则可能会发生多个生成项目相互覆盖的情况。

例如，对于 .NET 5 应用，输出路径将从 bin\Debug\net5.0 更改为 bin\Debug，并具有以下设置：

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

AppendRuntimeIdentifierToOutputPath

AppendRuntimeIdentifierToOutputPath 属性控制是否将运行时标识符 (RID) 追加到输出路径。 .NET SDK 会自动将目标框架以及运行时标识符（如果有）追加到输出路径。 将 AppendRuntimeIdentifierToOutputPath 设置为 false 可防止将 RID 追加到输出路径。

例如，对于 .NET 5 应用和 RID win10-x64，输出路径将从 bin\Debug\net5.0\win10-x64 更改为 bin\Debug\net5.0，并具有以下设置：

<PropertyGroup>
  <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

CopyLocalLockFileAssemblies

对于依赖于其他库的插件项目，CopyLocalLockFileAssemblies 属性非常有用。 如果将此属性设置为 true，系统会将所有 NuGet 包依赖项复制到输出目录。 这意味着，可以使用 dotnet build 的输出在任何计算机上运行插件。

<PropertyGroup>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

提示

或者，可以使用 dotnet publish 发布类库。 有关详细信息，请查看 dotnet publish。

ErrorOnDuplicatePublishOutputFiles

ErrorOnDuplicatePublishOutputFiles 属性与当 MSBuild 在发布输出中检测到重复文件时 SDK 是否生成错误 NETSDK1148 有关，但无法确定要删除的文件。 如果不希望生成错误，请将 ErrorOnDuplicatePublishOutputFiles 属性设置为 false。

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>

此属性是在 .NET 6 中引入的。

EnablePackageValidation

EnablePackageValidation 属性在 pack 任务后对包启用一系列验证。 有关详细信息，请参阅包验证。

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

此属性是在 .NET 6 中引入的。

GenerateRuntimeConfigDevFile

从 .NET 6 SDK 开始，在编译时默认不再生成 [Appname].runtimesettings.dev.json 文件。 如果仍希望生成此文件，请将 GenerateRuntimeConfigDevFile 属性设置为 true。

<PropertyGroup>
  <GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>

GenerateRuntimeConfigurationFiles

GenerateRuntimeConfigurationFiles 属性控制运行时配置选项是否从 runtimeconfig.template.json 文件复制到 [appname].runtimeconfig.json 文件。 对于需要 runtimeconfig.json 文件的应用（即，其 OutputType 为 Exe 的应用），此属性默认设置为 true。

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>

GenerateSatelliteAssembliesForCore

GenerateSatelliteAssembliesForCore 属性控制 .NET Framework 项目中的附属程序集是使用 csc.exe 还是 Al.exe（程序集链接器）生成的。 （.NET Core 和 .NET 5+ 项目始终使用 csc.exe 生成附属程序集。）对于 .NET Framework 项目，默认情况下，附属程序集由 al.exe 创建。 通过将 GenerateSatelliteAssembliesForCore 属性设置为 true，附属程序集会由 csc.exe 创建。 在以下情况下，使用 csc.exe 可能有利：

<PropertyGroup>
  <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>

IsPublishable

IsPublishable 属性允许 Publish 目标运行。 此属性仅影响使用 .*proj 文件和 Publish 目标的进程，例如 dotnet publish 命令。 它不会影响 Visual Studio 中使用 PublishOnly 目标的发布。 默认值为 true。

如果在解决方案文件上运行 dotnet publish，则此属性很有用，因为它允许自动选择应发布的项目。

<PropertyGroup>
  <IsPublishable>false</IsPublishable>
</PropertyGroup>

PreserveCompilationContext

PreserveCompilationContext 属性允许已构建或已发布的应用程序在运行时使用与构建时使用的相同设置来编译更多代码。 在构建时引用的程序集将被复制到输出目录的 ref 子目录中。 引用程序集的名称与传递给编译器的选项一起存储在应用程序的 .deps.json 文件中。 可使用 DependencyContext.CompileLibraries 和 DependencyContext.CompilationOptions 属性检索此信息。

此功能主要由 ASP.NET Core MVC 和 Razor Pages 在内部使用，以支持 Razor文件的运行时编译。

<PropertyGroup>
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

PreserveCompilationReferences

PreserveCompilationReferences 属性与 PreserveCompilationContext 属性类似，只不过它仅将引用的程序集复制到发布目录，而不是 .deps.json 文件。

<PropertyGroup>
  <PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>

有关详细信息，请参阅 Razor SDK 属性。

ProduceReferenceAssemblyInOutDir

在 .NET 5 及更早版本中，引用程序集始终写入 OutDir 目录。 在 .NET 6 及更高版本中，可以使用 ProduceReferenceAssemblyInOutDir 属性来控制引用程序集是否写入 OutDir 目录。 默认值为 false，并且引用程序集仅写入 IntermediateOutputPath 目录。 将值设置为 true，以将引用程序集写入 OutDir 目录。

<PropertyGroup>
  <ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>

有关详细信息，请参阅将引用程序集写入中间输出。

PublishRelease

PublishRelease 属性通知 dotnet publish 利用 Release 配置而不是 Debug 配置。 建议将此属性添加到 Directory.Build.props 文件（而不是项目文件），以便尽早对其进行评估，进而传播配置更改。

<PropertyGroup>
  <PublishRelease>true</PublishRelease>
</PropertyGroup>

注意

此属性不影响 dotnet build /t:Publish 的行为。

RollForward

RollForward 属性控制应用程序在有多个运行时版本可用时如何选择运行时。 此值作为 rollForward 设置输出到 .runtimeconfig.js。

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

将 RollForward 设置为以下值之一：

值 说明
Minor 如果未指定，则为默认值。
如果缺少所请求的次要版本，则前滚到最低的较高次要版本。 如果存在所请求的次要版本，则使用 LatestPatch 策略。
Major 如果缺少所请求的主要版本，则前滚到下一个可用的更高主要版本和最低的次要版本。 如果存在所请求的主要版本，则使用 Minor 策略。
LatestPatch 前滚到最高补丁版本。 此值会禁用次要版本前滚。
LatestMinor 即使存在所请求的次要版本，仍前滚到最高次要版本。
LatestMajor 即使存在所请求的主要版本，仍前滚到最高主要版本和最高次要版本。
Disable 不要前滚，仅绑定到指定的版本。 建议不要将此策略用于一般用途，因为它会禁用前滚到最新补丁的功能。 该值仅建议用于测试。

有关详细信息，请参阅控制前滚行为。

RuntimeFrameworkVersion

RuntimeFrameworkVersion 属性指定发布时要使用的运行时版本。 指定运行时版本：

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

当发布依赖于框架的应用程序时，此值指定所需的最低版本。 当发布自包含的应用程序时，此值指定所需的确切版本。

RuntimeIdentifier

RuntimeIdentifier 属性可用于指定项目的单个运行时标识符 (RID)。 RID 支持发布独立部署。

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

RuntimeIdentifiers

RuntimeIdentifiers 属性可用于指定项目的运行时标识符 (RID) 的列表（以分号分隔）。 如果需要为多个运行时发布，请使用此属性。 RuntimeIdentifiers 在还原时使用，以确保图中有适当的资产。

提示

RuntimeIdentifier（单数）可以在只需要一个运行时时提供更快的生成。

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

SatelliteResourceLanguages

SatelliteResourceLanguages 属性允许你指定要在生成和发布过程中为哪些语言保留附属资源程序集。 许多 NuGet 包将本地化资源附属程序集包含在主包中。 对于引用不需要本地化资源的 NuGet 包的项目，本地化程序集可能会不必要地增加生成和发布输出大小。 通过将 SatelliteResourceLanguages 属性添加到项目文件，只会将你指定的语言的本地化程序集包含在生成和发布输出中。 例如，在以下项目文件中，将只保留英语（美国）和德语（德国）的资源附属程序集。

<PropertyGroup>
  <SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

注意

必须在引用包含本地化资源附属程序集的 NuGet 包的项目中指定此属性。

UseAppHost

UseAppHost 属性控制是否为部署创建本机可执行文件。 自包含部署需要本机可执行文件。

在 .NET Core3.0 及更高版本中，默认情况下会创建依赖于框架的可执行文件。 将 UseAppHost 属性设置为 false 可禁用可执行文件的生成。

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

有关部署的详细信息，请参阅 .NET 应用程序部署。

许多 MSBuild 属性可用于对剪裁进行微调，此功能用于从自包含部署中剪裁未使用的代码。 剪裁选项中详细讨论了这些选项。 下表提供了快速参考。

属性 值 说明
PublishTrimmed true 或 false 控制是否在发布期间启用剪裁。
TrimMode full 或 partial 默认值为 full。 控制剪裁粒度。
SuppressTrimAnalysisWarnings true 或 false 控制是否生成剪裁分析警告。
EnableTrimAnalyzer true 或 false 控制是否生成剪裁分析警告的子集。 即使 PublishTrimmed 设置为 false，也可以启用分析。
ILLinkTreatWarningsAsErrors true 或 false 控制是否将剪裁警告视为错误。 例如，当 TreatWarningsAsErrors 设置为 true 时，可能需要将此属性设置为 false。
TrimmerSingleWarn true 或 false 控制是显示每个程序集的单个警告，还是显示所有警告。
TrimmerRemoveSymbols true 或 false 控制是否从已剪裁的应用程序中移除所有符号。

本节收录了以下 MSBuild 属性：

还可在项目文件中将 C# 编译器选项（如 LangVersion 和 Nullable）指定为 MSBuild 属性。 有关详细信息，请参阅 C# 编译器选项。

DisableImplicitFrameworkDefines

DisableImplicitFrameworkDefines 属性控制 SDK 是否会为 .NET 项目的目标框架和平台生成预处理器符号。 如果将此属性设置为 false 或未设置（这是默认值），则会为以下项生成预处理器符号：

  • 未带版本的框架（NETFRAMEWORK、NETSTANDARD、NET）
  • 带版本的框架（NET48、NETSTANDARD2_0、NET6_0）
  • 具有最低版本限制的框架（NET48_OR_GREATER、NETSTANDARD2_0_OR_GREATER、NET6_0_OR_GREATER）

若要详细了解目标框架名字对象和这些隐式预处理器符号，请参阅目标框架。

此外，如果在项目中指定特定于操作系统的目标框架（例如 net6.0-android），则会生成以下预处理器符号：

  • 未带版本的平台（ANDROID、IOS、WINDOWS）
  • 带版本的平台 (IOS15_1)
  • 具有最低版本限制的框架 (IOS15_1_OR_GREATER)

若要详细了解特定于操作系统的目标框架名字对象，请参阅特定于 OS 的 TFM。

最后，如果目标框架表示支持较旧的目标框架，则会发出这些较旧框架的预处理器符号。 例如，net6.0 表示支持 net5.0 至 .netcoreapp1.0。 因此，对于上述每种目标框架，将定义“具有最低版本限制的框架”符号。

DocumentationFile

通过 DocumentationFile 属性，可为包含库文档的 XML 文件指定文件名。 要使 IntelliSense 与文档一起正常运行，文件名必须与程序集名称相同，并且必须与程序集位于同一目录中。 如果不指定此属性，但将 GenerateDocumentationFile 设置为 true，则文档文件的名称默认为程序集的名称，但文件扩展名为 .xml。 由于这个原因，省略此属性并改用 GenerateDocumentationFile 属性通常更容易。

如果指定此属性，但将 GenerateDocumentationFile 设置为 false，编译器将不会生成文档文件。 如果指定此属性并省略 GenerateDocumentationFile 属性，编译器将生成文档文件。

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>

EmbeddedResourceUseDependentUponConvention

EmbeddedResourceUseDependentUponConvention 属性定义了是否从与资源文件并置的源文件中的类型信息生成资源清单文件名。 例如，如果 Form1.resx 与 Form1.cs 位于同一文件夹中，并且 EmbeddedResourceUseDependentUponConvention 设置为 true，则生成的 .resources 文件将采用 Form1.cs 中定义的第一个类型的名称作为其文件名。 例如，如果 Form1.cs 中定义的第一个类型为 MyNamespace.Form1，则生成的文件名为 MyNamespace.Form1.resources。

注意

如果为 EmbeddedResource 项指定 LogicalName、ManifestResourceName 或 DependentUpon 元数据，则为该资源文件生成的清单文件名将改为基于该元数据。

默认情况下，在新的 .NET 项目中，此属性设置为 true。 如果设置为 false，并且没有为项目文件中的 EmbeddedResource 项指定 LogicalName、ManifestResourceName 或 DependentUpon 元数据，则资源清单文件名将基于项目的根命名空间和 .resx 文件的相对文件路径。 有关详细信息，请参阅资源清单文件的命名。

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

EnablePreviewFeatures

EnablePreviewFeatures 属性定义项目是否依赖于使用 RequiresPreviewFeaturesAttribute 特性修饰的任何 API 或程序集。 此特性用于表示 API 或程序集使用的功能被视为是你正使用的 SDK 版本的预览功能。 不支持预览功能，并且可能会在将来的版本中删除这些功能。 若要启用预览功能，请将属性设置为 True。

<PropertyGroup>
  <EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>

当项目包含设置为 True 的属性时，以下程序集级别特性将添加到 AssemblyInfo.cs 文件中：

[assembly: RequiresPreviewFeatures]

当 EnablePreviewFeatures 未设置为 True 时，如果此特性存在于项目的依赖项中，分析器会发出警告。

要发运预览程序集的库作者应将此属性设置为 True。 如果程序集需要随预览 API 和非预览 API 一起提供，请参阅下面的 GenerateRequiresPreviewFeaturesAttribute 部分。

GenerateDocumentationFile

GenerateDocumentationFile 属性控制编译器是否为库生成 XML 文档文件。 如果将此属性设置为 true，并且你没有通过 DocumentationFile 属性指定文件名，生成的 XML 文件会放置在与程序集相同的输出目录中，并具有相同的文件名（但扩展名为 .xml）。

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

有关从代码注释生成文档的详细信息，请参阅 XML 文档注释 (C#)、使用 XML 记录代码 (Visual Basic) 或使用 XML 记录代码 (F#)。

GenerateRequiresPreviewFeaturesAttribute

GenerateRequiresPreviewFeaturesAttribute 属性与 EnablePreviewFeatures 属性密切相关。 如果库使用预览功能，但不希望使用 RequiresPreviewFeaturesAttribute 特性标记整个程序集（需要任何使用者启用预览功能），请将此属性设置为 False。

<PropertyGroup>
    <EnablePreviewFeatures>True</EnablePreviewFeatures>
    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>

重要

如果将 GenerateRequiresPreviewFeaturesAttribute 属性设置 False，则一定要使用 RequiresPreviewFeaturesAttribute 修饰依赖于预览功能的所有公共 API。

OptimizeImplicitlyTriggeredBuild

为了加快生成时间，Visual Studio 隐式触发的生成将跳过代码分析（包括可为 null 的分析）。 例如，当运行测试时，Visual Studio 触发隐式生成。 但是，仅当 TreatWarningsAsErrors 不是 true 时，才会优化隐式生成。 如果将 TreatWarningsAsErrors 设置为 true，但仍希望优化已隐式触发的生成，则可以将 OptimizeImplicitlyTriggeredBuild 设置为 True。 若要关闭隐式触发的生成的生成优化，请将 OptimizeImplicitlyTriggeredBuild 设置为 False。

<PropertyGroup>
    <OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>

默认项包含属性

本节收录了以下 MSBuild 属性：

有关详细信息，请参阅默认的包括和排除。

DefaultItemExcludes

使用 DefaultItemExcludes 属性定义需从“包括”、“排除”和“删除”glob 中排除的文件和文件夹的 glob 模式。 默认情况下从 glob 模式中排除 ./bin 和 ./obj 文件夹 。

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>

DefaultItemExcludesInProjectFolder

使用 DefaultItemExcludesInProjectFolder 属性定义项目文件夹中需要从“包括”、“排除”和“删除”glob 中排除的文件和文件夹的 glob 模式。 默认情况下，从 glob 模式中排除以句点 (.) 开头的文件夹，如 .git 和 .vs。

此属性与 DefaultItemExcludes 属性非常相似，不同之处在于它只涉及项目文件夹中的文件和文件夹。 如果 glob 模式会无意中将项目文件夹外部的项与相对路径进行匹配，请使用 DefaultItemExcludesInProjectFolder 属性，而不是 DefaultItemExcludes 属性。

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</PropertyGroup>

EnableDefaultItems

EnableDefaultItems 属性控制是否在项目中隐式包含编译项、嵌入的资源项和 None 项。 默认值为 true。 若要禁用所有隐式文件包含，请将 EnableDefaultItems 属性设置为 false。

<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>

EnableDefaultCompileItems

EnableDefaultCompileItems 属性控制是否在项目中隐式包含编译项。 默认值为 true。 将 EnableDefaultCompileItems 属性设置为 false 以禁用 * .cs 和其他语言扩展文件的隐式包含。

<PropertyGroup>
  <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>

EnableDefaultEmbeddedResourceItems

EnableDefaultEmbeddedResourceItems 属性控制是否在项目中隐式包含嵌入的资源项。 默认值为 true。 将 EnableDefaultEmbeddedResourceItems 属性设置为 false 以禁用嵌入的资源文件的隐式包含。

<PropertyGroup>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>

EnableDefaultNoneItems

EnableDefaultNoneItems 属性控制是否在项目中隐式包含 None 项（生成过程中未赋予角色的文件）。 默认值为 true。 将 EnableDefaultNoneItems 属性设置为 false 以禁用 None 项的隐式包含。

<PropertyGroup>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>

代码分析属性

本节收录了以下 MSBuild 属性：

AnalysisLevel

AnalysisLevel 属性使你可以指定一组代码分析器，以根据 .NET 版本进行运行。 从 .NET 5 开始，每个 .NET 版本都有一组代码分析规则。 在这组规则中，默认为该版本启用的规则将分析代码。 例如，如果升级到 .NET 6，但不希望更改默认的这组代码分析规则，请将 AnalysisLevel 设置为 5。

<PropertyGroup>
  <AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>

（可选）从 .NET 6 开始，可以为此属性指定复合值，该值还指定启用规则的积极程度。 复合值采用形式 <version>-<mode>，其中 <mode> 值是 AnalysisMode 值之一。 以下示例使用代码分析器预览版，并启用建议的规则集。

<PropertyGroup>
  <AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>

注意

如果将 AnalysisLevel 设置为 5-<mode> 或 5.0-<mode>，然后安装 .NET 6 SDK 并重新编译项目，可能会看到意外的新生成警告。 有关详细信息，请参阅 dotnet/roslyn-analyzers#5679。

默认值：

  • 如果你的项目以 .NET 5 或更高版本为目标，或你添加了 AnalysisMode 属性，则默认值为 latest。
  • 否则，此属性被省略，除非你将它明确添加到项目文件中。

下表显示可以指定的值。

值 含义
latest 使用已发布的最新版代码分析器。 这是默认值。
latest-<mode> 使用已发布的最新版代码分析器。 <mode> 值确定启用哪些规则。
preview 使用最新的代码分析器（即使它们处于预览状态）。
preview-<mode> 使用最新的代码分析器（即使它们处于预览状态）。 <mode> 值确定启用哪些规则。
6.0 即使有较新的规则可用，也会使用可用于 .NET 6 版本的规则集。
6.0-<mode> 即使有较新的规则可用，也会使用可用于 .NET 6 版本的规则集。 <mode> 值确定启用哪些规则。
6 即使有较新的规则可用，也会使用可用于 .NET 6 版本的规则集。
6-<mode> 即使有较新的规则可用，也会使用可用于 .NET 6 版本的规则集。 <mode> 值确定启用哪些规则。
5.0 即使有较新的规则可用，也会使用可用于 .NET 5 版本的规则集。
5.0-<mode> 即使有较新的规则可用，也会使用可用于 .NET 5 版本的规则集。 <mode> 值确定启用哪些规则。
5 即使有较新的规则可用，也会使用可用于 .NET 5 版本的规则集。
5-<mode> 即使有较新的规则可用，也会使用可用于 .NET 5 版本的规则集。 <mode> 值确定启用哪些规则。

注意

  • 在 .NET 5 以及更早版本中，此属性仅影响代码质量 (CAXXXX) 规则。 从 .NET 6 开始，如果将 EnforceCodeStyleInBuild 设置为 true，则此属性也会影响代码样式 (IDEXXXX) 规则。
  • 如果为 AnalysisLevel 设置复合值，则无需指定 AnalysisMode。 但是，如果这样做，AnalysisLevel 会优先于 AnalysisMode。
  • 此属性对未引用项目 SDK 的项目（例如，引用 Microsoft.CodeAnalysis.NetAnalyzers NuGet 包的旧版 .NET Framework 项目）中的代码分析没有影响。

AnalysisLevel<Category>

.NET 6 中引入的此属性与 AnalysisLevel 相同，但仅适用于特定的代码分析规则类别。 此属性使你能够为特定类别使用不同版本的代码分析器，或在其他规则类别的不同级别启用或禁用规则。 如果为特定规则类别省略此属性，则其默认为 AnalysisLevel 值。 可用值与 AnalysisLevel 相同。

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>

<PropertyGroup>
  <AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>

下表列出了每个规则类别的属性名称。

属性名称 规则类别
<AnalysisLevelDesign> 设计规则
<AnalysisLevelDocumentation> 文档规则
<AnalysisLevelGlobalization> 全球化规则
<AnalysisLevelInteroperability> 可移植性和互操作性规则
<AnalysisLevelMaintainability> 可维护性规则
<AnalysisLevelNaming> 命名规则
<AnalysisLevelPerformance> 性能规则
<AnalysisLevelSingleFile> 单文件应用程序规则
<AnalysisLevelReliability> 可靠性规则
<AnalysisLevelSecurity> 安全规则
<AnalysisLevelStyle> 代码样式 (IDEXXXX) 规则
<AnalysisLevelUsage> 用法规则

AnalysisMode

从 .NET 5 开始，.NET SDK 附带了所有“CA”代码质量规则。 默认情况下，在每个 .NET 发布版中，只有一些规则作为生成警告启用。 AnalysisMode 属性允许自定义默认启用的一组规则。 你可以切换到更激进的分析模式（可以单独选择不使用规则），或者切换到更保守的分析模式（可以选择使用特定规则）。 例如，如果要作为生成警告启用所有规则，请将值设置为 All。

<PropertyGroup>
  <AnalysisMode>All</AnalysisMode>
</PropertyGroup>

下表显示了 .NET 5 和 .NET 6 中可用的选项值。 它们按其启用的规则数的增加顺序列出。

.NET 6+ 值 .NET 5 值 含义
None AllDisabledByDefault 所有规则都处于禁用状态。 可以选择选择加入各条规则，以启用它们。
Default Default 默认模式，其中某些规则作为生成警告启用，某些规则作为 Visual Studio IDE 建议启用，其余规则被禁用。
Minimum 不适用 比 Default 模式更主动的模式。 强烈建议生成实施的某些建议作为生成警告启用。
Recommended 空值 比 Minimum 模式更主动的模式，其中启用了更多规则作为生成警告。
All AllEnabledByDefault 所有规则作为生成警告启用。 可以选择选择退出各条规则，以禁用它们。

注意

  • 在 .NET 5 中，此属性仅影响代码质量 (CAXXXX) 规则。 从 .NET 6 开始，如果将 EnforceCodeStyleInBuild 设置为 true，则此属性也会影响代码样式 (IDEXXXX) 规则。
  • 如果使用 AnalysisLevel 的复合值（如 <AnalysisLevel>5-recommended</AnalysisLevel>），则可以完全省略此属性。 但是，如果同时指定这两个属性，则 AnalysisLevel 会优先于 AnalysisMode。
  • 如果将 AnalysisMode 设置为 AllEnabledByDefault，并将 AnalysisLevel 设置为 5 或 5.0，然后安装 .NET 6 SDK 并重新编译项目，可能会看到意外的新生成警告。 有关详细信息，请参阅 dotnet/roslyn-analyzers#5679。
  • 此属性对未引用项目 SDK 的项目（例如，引用 Microsoft.CodeAnalysis.NetAnalyzers NuGet 包的旧版 .NET Framework 项目）中的代码分析没有影响。

AnalysisMode<Category>

.NET 6 中引入的此属性与 AnalysisMode 相同，但仅适用于特定的代码分析规则类别。 此属性使你能够在其他规则类别的不同级别启用或禁用规则。 如果为特定规则类别省略此属性，则其默认为 AnalysisMode 值。 可用值与 AnalysisMode 相同。

<PropertyGroup>
  <AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>

下表列出了每个规则类别的属性名称。

属性名称 规则类别
<AnalysisModeDesign> 设计规则
<AnalysisModeDocumentation> 文档规则
<AnalysisModeGlobalization> 全球化规则
<AnalysisModeInteroperability> 可移植性和互操作性规则
<AnalysisModeMaintainability> 可维护性规则
<AnalysisModeNaming> 命名规则
<AnalysisModePerformance> 性能规则
<AnalysisModeSingleFile> 单文件应用程序规则
<AnalysisModeReliability> 可靠性规则
<AnalysisModeSecurity> 安全规则
<AnalysisModeStyle> 代码样式 (IDEXXXX) 规则
<AnalysisModeUsage> 用法规则

CodeAnalysisTreatWarningsAsErrors

CodeAnalysisTreatWarningsAsErrors 属性可配置是否应将代码质量分析警告 (CAxxxx) 视为警告并中断生成。 如果在生成项目时使用 -warnaserror 标志，则 .NET 代码质量分析警告也会被视为错误。 如果不希望将代码质量分析警告视为错误，可以在项目文件中将 CodeAnalysisTreatWarningsAsErrors MSBuild 属性设置为 false。

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

EnableNETAnalyzers

默认情况下，为面向 .NET 5 或更高版本的项目启用 .NET 代码质量分析。 如果你是使用 .NET 5+ SDK 进行开发，可通过将 EnableNETAnalyzers 属性设置为 true，来为面向 .NET 早期版本的 SDK 样式项目启用 .NET 代码分析。 若要禁用任何项目中的代码分析，可将此属性设置为 false。

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

注意

此属性专门用于 .NET 5 及更高版本 SDK 中的内置分析器。 安装 NuGet 代码分析包时不应使用此属性。

EnforceCodeStyleInBuild

对于所有 .NET 项目的版本，.NET 代码样式分析默认处于禁用状态。 通过将 EnforceCodeStyleInBuild 属性设置为 true，可以为 .NET 项目启用代码样式分析。

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

生成和报告违规时将执行配置为警告或错误的所有代码样式规则。

注意

如果安装 .NET 6（或者包含 .NET 6 的 Visual Studio 2022），但想要使用 Visual Studio 2019 生成项目，则在 EnforceCodeStyleInBuild 属性设置为 true 的情况下，你可能会看到新的 CS8032 警告。 若要解决这些警告，可通过添加 global.json 条目，指定要用于生成项目的 .NET SDK 版本（在本例中，类似于 5.0.404）。

_SkipUpgradeNetAnalyzersNuGetWarning

与最新的 .NET SDK 中的代码分析器相比，使用过期的 NuGet 包中的代码分析器时，可使用 _SkipUpgradeNetAnalyzersNuGetWarning 属性来配置是否收到警告。 该警告类似于：

.NET SDK 具有比“Microsoft.CodeAnalysis.NetAnalyzers”包的“5.0.3”版本所提供内容更新的“6.0.0”版本分析器。 更新或删除此包引用。

若要删除此警告并继续使用 NuGet 包中的代码分析器版本，请在你的项目文件中将 _SkipUpgradeNetAnalyzersNuGetWarning 设置为 true。

<PropertyGroup>
  <_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>

运行时配置属性

可以通过在应用的项目文件中指定 MSBuild 属性来配置某些运行时行为。 有关配置运行时行为的其他方法的信息，请参阅运行时配置设置。

ConcurrentGarbageCollection

ConcurrentGarbageCollection 属性配置是否启用 后台（并发）垃圾回收。 将值设置为 false 以禁用后台垃圾回收。 有关详细信息，请参阅后台 GC。

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

InvariantGlobalization

InvariantGlobalization 属性配置应用是否在全球化固定模式下运行，这意味着它无权访问特定于区域性的数据。 将值设置为 true 以在全球化固定模式下运行。 有关详细信息，请参阅固定模式。

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

PredefinedCulturesOnly

在 .NET 6 及更高版本中，PredefinedCulturesOnly 属性配置应用在启用全球化固定模式时，是否可以创建除固定区域性之外的区域性。 默认为 true。 将值设置为 false 可在全球化固定模式下创建任何新区域性。

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

有关详细信息，请参阅全球化固定模式下的区域性创建和大小写映射。

RetainVMGarbageCollection

RetainVMGarbageCollection 属性配置垃圾回收器，以将已删除的内存段放置在备用列表上供将来使用或释放它们。 将值设置为 true 会告知垃圾回收器将段放在备用列表上。 有关详细信息，请参阅保留 VM。

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

ServerGarbageCollection

ServerGarbageCollection 属性配置应用程序是使用工作站垃圾回收还是服务器垃圾回收。 将值设置为 true 以使用服务器垃圾回收。 有关详细信息，请参阅工作站与服务器。

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

ThreadPoolMaxThreads

ThreadPoolMaxThreads 属性配置工作线程池的最大线程数。 有关详细信息，请参阅最大线程数。

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

ThreadPoolMinThreads

ThreadPoolMinThreads 属性配置工作线程池的最小线程数。 有关详细信息，请参阅最小线程数。

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

TieredCompilation

TieredCompilation 属性配置实时 (JIT) 编译器是否使用分层编译。 将值设置为 false 以禁用分层编译。 有关详细信息，请参阅分层编译。

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

TieredCompilationQuickJit

TieredCompilationQuickJit 属性配置 JIT 编译器是否使用快速 JIT。 将值设置为 false 以禁用快速 JIT。 有关详细信息，请参阅快速 JIT。

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

TieredCompilationQuickJitForLoops

TieredCompilationQuickJitForLoops 配置 JIT 编译器是否对包含循环的方法使用快速 JIT。 将值设置为 true 以对包含循环的方法启用快速 JIT。 有关详细信息，请参阅适用于循环的快速 JIT。

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

引用属性

本节收录了以下 MSBuild 属性：

AssetTargetFallback

使用 AssetTargetFallback 属性，可以为项目引用和 NuGet 包指定其他兼容的框架版本。 例如，如果使用 PackageReference 指定包依赖项，但该包不包含与项目的 TargetFramework 兼容的资源，则可使用 AssetTargetFallback 属性。 使用 AssetTargetFallback 中指定的每个目标框架重新检查引用包的兼容性。 此属性替换已弃用的属性 PackageTargetFallback。

可以将 AssetTargetFallback 属性设置为一个或多个目标框架版本。

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

DisableImplicitFrameworkReferences

面向 .NET Core 3.0 及更高版本时，DisableImplicitFrameworkReferences 属性会控制隐式 FrameworkReference 项。 面向 .NET Core 2.1 或 .NET Standard 2.0 及早期版本时，该属性会控制元包中包的隐式 PackageReference 项。 （元包是基于框架的包，仅包含对其他包的依赖项。）此属性还控制以 .NET framework 为目标时的隐式引用，如 System 和 System.Core。

将此属性设置为 true 以禁用隐式 FrameworkReference 或 PackageReference 项。 如果将此属性设置为 true，则可以仅添加对所需框架或包的显式引用。

<PropertyGroup>
  <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>

DisableTransitiveProjectReferences

DisableTransitiveProjectReferences 属性控制隐式项目引用。 将此属性设置为 true 以禁用隐式 ProjectReference 项。 禁用隐式项目引用会导致与旧项目系统类似的非可传递行为。

当此属性为 true 时，它与在依赖项目的所有依赖项上设置 PrivateAssets="All" 的效果类似。

如果将此属性设置为 true，则可以仅添加对所需项目的显式引用。

<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

还原被引用的包会安装它的所有直接依赖项，以及这些依赖项的全部依赖项。 可以通过指定 RestorePackagesPath 和 RestoreIgnoreFailedSources 等属性来自定义包还原。 若要详细了解这些属性和其他属性，请参阅还原目标。

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

ValidateExecutableReferencesMatchSelfContained

ValidateExecutableReferencesMatchSelfContained 属性可用于禁用与可执行项目引用相关的错误。 如果 .NET 检测到独立可执行文件项目引用依赖于框架的可执行项目，或相反，则会分别生成错误 NETSDK1150 和 NETSDK1151。 若要避免在引用是有意而为之时出现这些错误，请将 ValidateExecutableReferencesMatchSelfContained 属性设置为 false。

<PropertyGroup>
  <ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>

WindowsSdkPackageVersion

WindowsSdkPackageVersion 属性可用于替代 Windows SDK 目标包的版本。 此属性是在 .NET 5 中引入的，并出于此目的替换了 FrameworkReference 项的使用。

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

注意

不建议替代 Windows SDK 版本，因为 .NET 5+SDK 中包含 Windows SDK 目标包。 若要引用最新的 Windows SDK 包，请更新 .NET SDK 的版本。 此属性仅应在极少数情况下使用，例如使用预览包或需要替代 C#/WinRT 的版本。

以下属性用于使用 dotnet run 命令启动应用：

RunArguments

RunArguments 属性定义了在应用运行时向其传递的参数。

<PropertyGroup>
  <RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>

提示

可以使用 dotnet run 的 -- 选项来指定要传递到应用的其他参数。

RunWorkingDirectory

RunWorkingDirectory 属性定义要用于启动应用程序进程的工作目录。 它可以是绝对路径，也可以是相对于项目目录的路径。 如果未指定目录，OutDir 将用作工作目录。

<PropertyGroup>
  <RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>

本节收录了以下 MSBuild 属性：

EnableComHosting

EnableComHosting 属性表示程序集提供了 COM 服务器。 将 EnableComHosting 设置为 true 也表明 EnableDynamicLoading 为 true。

<PropertyGroup>
  <EnableComHosting>True</EnableComHosting>
</PropertyGroup>

有关详细信息，请参阅向 COM 公开 .NET 组件。

EnableDynamicLoading

EnableDynamicLoading 属性指示程序集是动态加载的组件。 组件可以是 COM 库，也可以是在本机主机中使用或用作插件的非 COM 库。 将此属性设置为 true 会产生以下结果：

  • 生成 runtimeconfig.json 文件。
  • RollForward 设置为 LatestMinor。
  • 在本地复制 NuGet 引用。
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

生成的文件属性

以下属性与生成的文件中的代码有关：

DisableImplicitNamespaceImports

DisableImplicitNamespaceImports 属性可用于在面向 .NET 6 或更高版本的 Visual Basic 项目中禁用隐式命名空间导入。 隐式命名空间是 Visual Basic 项目中全局导入的默认命名空间。 将此属性设置为 true 可禁用隐式命名空间导入。

<PropertyGroup>
  <DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>

ImplicitUsings

ImplicitUsings 属性可用于在面向 .NET 6（或更高版本）和 C# 10（或更高版本）的 C# 项目中禁用隐式 global using 指令。 启用该功能后，.NET SDK 会根据项目 SDK 的类型为一组默认命名空间添加 global using 指令。 将此属性设置为 true 或 enable 可启用隐式 global using 指令。 若要禁用隐式 global using 指令，请删除该属性或将其设置为 false 或 disable。

<PropertyGroup>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

注意

面向 .NET 6 或更高版本的 C# 新项目的模板将 ImplicitUsings 默认设置为 enable。

若要定义显式 global using 指令，请添加 Using 项。

项

MSBuild 项是生成系统的输入。 根据项的类型（即元素名称）指定项。 例如，Compile 和 Reference 是两个常见项类型。 .NET SDK 提供了以下附加项类型：

你可以在这些项上使用任何标准的项目属性，例如 Include 和 Update。 使用 Include 添加新项，使用 Update 修改现有项。 例如，Update 通常用于修改由 .NET SDK 隐式添加的项。

AssemblyMetadata

AssemblyMetadata 项指定键值对 AssemblyMetadataAttribute 程序集特性。 Include 元数据将成为密钥，Value 元数据将成为值。

<ItemGroup>
  <AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>

InternalsVisibleTo

InternalsVisibleTo 项为指定的友元程序集生成 InternalsVisibleToAttribute 程序集特性。

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>

如果友元程序集已签名，则可以指定可选的 Key 元数据来指定其完整公钥。 如果未指定 Key 元数据，并且 $(PublicKey) 可用，则使用该密钥。 否则，不会向该特性添加公钥。

PackageReference

PackageReference 项定义了对 NuGet 包的引用。

Include 属性指定包 ID。 Version 特性指定版本或版本范围。 若要了解如何指定最低版本、最高版本、范围或完全匹配，请参阅版本范围。

以下示例中的项目文件片段引用 System.Runtime 包。

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

你还可以使用元数据（例如 PrivateAssets）来控制依赖项资产。

<ItemGroup>
  <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

有关详细信息，请参阅项目文件中的包引用。

TrimmerRootAssembly

TrimmerRootAssembly 项允许通过修整排除程序集。 修整是从打包的应用程序中删除运行时未使用部分的过程。 在某些情况下，修整可能会错误地删除所需的引用。

以下 XML 通过修整排除 System.Security 程序集。

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

有关详细信息，请参阅剪裁选项。

使用

Using 项可在整个 C# 项目中全局添加命名空间，因此不必在源文件顶部为命名空间添加 using 指令。 此项类似于可在 Visual Basic 项目中实现相同目的的 Import 项。 从 .NET 6 开始，就可使用此属性。

<ItemGroup>
  <Using Include="My.Awesome.Namespace" />
</ItemGroup>

还可使用 Using 项来定义全局 using <alias> 和 using static <type> 指令。

<ItemGroup>
  <Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>

例如：

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" /> 发出 global using Results = global::Microsoft.AspNetCore.Http.Results;
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" /> 发出 global using static global::Microsoft.AspNetCore.Http.Results;

若要详细了解别名 using 指令和 using static <type> 指令，请参阅 using 指令。

项元数据

除了标准的 MSBuild 项目属性之外，.net SDK 还提供以下项元数据标记：

CopyToPublishDirectory

MSBuild 项上的 CopyToPublishDirectory 元数据控制何时将项复制到发布目录。 允许的值为 PreserveNewest（仅在项已更改时复制项）、Always（始终复制项）和 Never（从不复制项）。 从性能角度来看，PreserveNewest 更为可取，因为它可实现增量生成。

<ItemGroup>
  <None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

LinkBase

对于项目目录及其子目录之外的项，发布目标使用项的链接元数据来确定要将项复制到的位置。 Link 还将确定项目树外的项在 Visual Studio 的“解决方案资源管理器”窗口中的显示方式。

如果没有为项目圆锥之外的项指定 Link，则默认为 %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension)。 通过 LinkBase，可以为项目圆锥之外的项指定一个合理的基础文件夹。 基础文件夹下的文件夹层次结构通过 RecursiveDir 保留。 如果未指定 LinkBase，则将从 Link 路径中省略它。

<ItemGroup>
  <Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>

下图显示通过上一个项 Include glob 包含的文件在解决方案资源管理器中的显示方式。

解决方案资源管理器，显示具有 LinkBase 元数据的项。

请参阅