.NET SDK 项目的 MSBuild 引用

  • 项目

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

注意

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

程序集验证属性

这些属性和项会传递给 ValidateAssemblies 任务。 有关程序集验证的详细信息，请参阅程序集验证。

本节收录了以下 MSBuild 属性：

注意

这些属性（尚）不是 .NET SDK 的一部分。 要使用它们，还必须将 PackageReference 添加到 Microsoft.DotNet.ApiCompat.Task。

此外，包验证属性中记录的以下属性也适用于程序集验证：

ApiCompatStrictMode

设置为 true 时，ApiCompatStrictMode 属性指定应在严格模式下执行 API 兼容性检查。

<PropertyGroup>
  <ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>

ApiCompatValidateAssemblies

ApiCompatValidateAssemblies 属性对指定的程序集启用一系列验证。 有关详细信息，请参阅程序集验证。

<PropertyGroup>
  <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>

框架属性

本节收录了以下 MSBuild 属性：

TargetFramework

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

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

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

TargetFrameworks

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

注意

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

<PropertyGroup>
  <TargetFrameworks>net8.0;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 时，与包相关的项目属性将转换为程序集特性。

若要详细了解如何使用项目文件生成程序集属性，请参阅在项目文件中设置程序集属性。

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 的默认行为。 此属性是在 .NET 7 中引入的。

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

注意

  • 从 .NET 8 SDK 开始，PackRelease 默认为 true。 有关详细信息，请参阅“dotnet pack”使用发布配置。
  • 仅限 .NET 7 SDK：若要在属于 Visual Studio 解决方案的项目中使用 PackRelease，必须将环境变量 DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS 设置为 true（或任何其他值）。 对于具有多个项目的解决方案，设置此变量会增加打包所需的时间。

包验证属性

这些属性和项会传递给 ValidatePackage 任务。 有关包验证的详细信息，请参阅包验证概述。

有关 ValidateAssemblies 任务的属性，请参阅程序集验证属性。

本部分记录了以下 MSBuild 属性和项：

ApiCompatEnableRuleAttributesMustMatch

设置为 true 时，ApiCompatEnableRuleAttributesMustMatch 属性将启用验证规则来检查属性是否匹配。 默认为 false。

<PropertyGroup>
  <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
</PropertyGroup>

ApiCompatEnableRuleCannotChangeParameterName

设置为 true 时，ApiCompatEnableRuleCannotChangeParameterName 属性将启用验证规则来检查参数名称是否已在公共方法中更改。 默认为 false。

<PropertyGroup>
  <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
</PropertyGroup>

ApiCompatExcludeAttributesFile

ApiCompatExcludeAttributesFile 项指定文件的路径，该文件包含要以 DocId 格式排除的属性。

<ItemGroup>
  <ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
  <ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
</ItemGroup>

ApiCompatGenerateSuppressionFile

ApiCompatGenerateSuppressionFile 属性指定是否生成兼容性抑制文件。

<PropertyGroup>
  <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
</PropertyGroup>

ApiCompatPermitUnnecessarySuppressions

ApiCompatPermitUnnecessarySuppressions 属性指定是否允许抑制文件中不必要的抑制。

默认值为 false。

<PropertyGroup>
  <ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
</PropertyGroup>

ApiCompatPreserveUnnecessarySuppressions

ApiCompatPreserveUnnecessarySuppressions 属性指定在重新生成抑制文件时是否保留不必要的抑制。 重新生成现有抑制文件时，会读取该文件的内容，将其反序列化为一组抑制，然后将其存储在列表中。 如果修复了不兼容问题，则可能不再需要某些抑制。 当抑制被序列化回磁盘时，可以选择通过将此属性设置为 true 来保留所有现有的（已反序列化的）表达式。

默认为 false。

<PropertyGroup>
  <ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
</PropertyGroup>

ApiCompatRespectInternals

ApiCompatRespectInternals 属性指定除了 public API 外，是否还应检查 internal API 的兼容性。

<PropertyGroup>
  <ApiCompatRespectInternals>true</ApiCompatRespectInternals>
</PropertyGroup>

ApiCompatSuppressionFile

ApiCompatSuppressionFile 项指定要从中读取的一个或多个抑制文件的路径。 如果未指定，则读取抑制文件 <project-directory>/CompatibilitySuppressions.xml（如果存在）。

<ItemGroup>
  <ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
</ItemGroup>

ApiCompatSuppressionOutputFile

ApiCompatSuppressionOutputFile 属性指定当 <ApiCompatGenerateSuppressionFile> 为 true 时要写入到的抑制文件的路径。 如果未指定，则使用第一个 ApiCompatSuppressionFile 项。

EnablePackageValidation

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

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

EnableStrictModeForBaselineValidation

设置为 true 时，EnableStrictModeForBaselineValidation 属性为包基线检查启用严格模式。 默认为 false。

EnableStrictModeForCompatibleFrameworksInPackage

设置为 true 时，EnableStrictModeForCompatibleFrameworksInPackage 属性为基于目标框架兼容的程序集启用严格模式。 默认值为 false。

EnableStrictModeForCompatibleTfms

设置为 true 时，EnableStrictModeForCompatibleTfms 属性为所有兼容目标框架的协定和实现程序集启用严格模式。 默认为 true。

NoWarn

NoWarn 属性指定要抑制的诊断 ID。

<PropertyGroup>
  <NoWarn>$(NoWarn);PKV0001</NoWarn>
</PropertyGroup>

PackageValidationBaselineFrameworkToIgnore

PackageValidationBaselineFrameworkToIgnore 指定要从基线包中忽略的目标框架。 框架字符串必须与基线包中的文件夹名称完全匹配。

<ItemGroup>
  <PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
</ItemGroup>

PackageValidationBaselineName

PackageValidationBaselineName 属性指定验证当前包所依据的基线包的名称。 如果未指定，则使用 PackageId 值。

PackageValidationBaselineVersion

PackageValidationBaselineVersion 属性指定验证当前包所依据的基线包的版本。

PackageValidationReferencePath

PackageValidationReferencePath 项指定每个 TFM 可在其中找到引用程序集的目录路径。

<ItemGroup>
  <PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
</ItemGroup>

RoslynAssembliesPath

RoslynAssembliesPath 属性指定包含要使用的 Microsoft.CodeAnalysis 程序集的目录的路径。 只有当你想要使用比 SDK 中的编译器版本更高的编辑器进行测试，才需要设置此属性。

本节收录了以下 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 win-x64，以下设置将输出路径从 bin\Debug\net5.0\win-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 中引入的。

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>

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

PublishDocumentationFile

当此属性为 true 时，项目的 XML 文档文件（如果已生成）包含在项目的发布输出中。 此属性的默认值为 true。

提示

将 GenerateDocumentationFile 设置为 true，以在编译时生成 XML 文档文件。

PublishDocumentationFiles

此属性是其他几个属性的启用标志，用于控制默认是否将各种 XML 文档文件复制到发布目录，即 PublishDocumentationFile 和 PublishReferencesDocumentationFiles。 如果未设置那些属性，而是设置了此属性，则这些属性将默认为 true。 此属性的默认值为 true。

PublishReferencesDocumentationFiles

当此属性为 true 时，将项目的引用的 XML 文档文件复制到发布目录，而不只是运行时资产（如 DLL 文件）。 此属性的默认值为 true。

PublishRelease

PublishRelease 属性通知 dotnet publish 默认使用 Release 配置而不是 Debug 配置。 此属性是在 .NET 7 中引入的。

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

注意

  • 从 .NET 8 SDK 开始，对于面向 .NET 8 或更高版本的项目，PublishRelease 默认为 true。 有关详细信息，请参阅“dotnet publish”使用发布配置。
  • 此属性不会影响 dotnet build /t:Publish 的行为，仅在通过 .NET CLI 发布时更改配置。
  • 仅限 .NET 7 SDK：若要在属于 Visual Studio 解决方案的项目中使用 PublishRelease，必须将环境变量 DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS 设置为 true（或任何其他值）。 发布已启用此变量的解决方案时，可执行项目的 PublishRelease 值优先，并将新的默认配置流向解决方案中的任何其他项目。 如果解决方案包含具有不同 PublishRelease 值的多个可执行文件或顶级项目，则解决方案将无法成功发布。 对于具有多个项目的解决方案，使用此设置会增加发布所需的时间。

PublishSelfContained

该 PublishSelfContained 属性通知 dotnet publish 将应用发布为自包含应用。 当不能将参数“--self-contained”用于 dotnet publish 命令时（例如，在解决方案级别发布时），此属性非常有用。 在这种情况下，可以将 PublishSelfContained MSBuild 属性添加到项目或 Directory.Build.Props 文件中。

此属性是在 .NET 7 中引入的。 它类似于 SelfContained 属性，只是它特定于 publish 谓词。 建议使用 PublishSelfContained 而不是 SelfContained。

<PropertyGroup>
  <PublishSelfContained>true</PublishSelfContained>
</PropertyGroup>

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>linux-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

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

提示

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

<PropertyGroup>
  <RuntimeIdentifiers>win-x64;osx-x64;linux-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

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

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

注意

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

  • 若要将多种语言指定为 dotnet publish 的参数，必须在语言标识符周围添加三对引号。 例如：

    dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""

SelfContained

该 SelfContained 属性通知 dotnet build 和 dotnet publish 将应用构建或发布为自包含应用。 当不能将参数“--self-contained”用于 dotnet 命令时（例如，在解决方案级别发布时），此属性非常有用。 在这种情况下，可以将 SelfContained MSBuild 属性添加到项目或 Directory.Build.Props 文件中。

此属性类似于 PublishSelfContained 属性。 建议尽可能使用 PublishSelfContained 而不是 SelfContained。

<PropertyGroup>
  <SelfContained>true</SelfContained>
</PropertyGroup>

UseAppHost

UseAppHost 属性控制是否为部署创建本机可执行文件。 自包含部署需要本机可执行文件。 默认情况下会创建依赖于框架的可执行文件。 将 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# 编译器选项。

ContinuousIntegrationBuild

ContinuousIntegrationBuild 属性指示生成是否在持续集成 (CI) 服务器上执行。 当设置为 true 时，此属性将启用的设置仅适用于官方内部版本，不适用于开发人员计算机上的本地内部版本。 例如，存储的文件路径针对官方内部版本进行了规范化。 但在本地开发计算机上，如果文件路径进行了规范化，调试程序将无法找到本地源文件。

注意

目前，仅当添加特定的 SourceLink 提供程序包引用或 <SourceRoot Include="$(MyDirectory)" /> 项时，将此属性设置为 true 才起作用。 有关详细信息，请参阅 dotnet/roslyn 问题 55860。

可以使用 CI 系统的变量有条件地设置 ContinuousIntegrationBuild 属性。 例如，Azure Pipelines 的变量名称为 TF_BUILD：

<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

对于 GitHub Actions，变量名称为 GITHUB_ACTIONS：

<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

CopyDebugSymbolFilesFromPackages

当此属性设置为 true 时，将项目中 PackageReference 项的所有符号文件（也称为 PDB 文件）复制到生成输出。 这些文件可以为异常提供更有意义的堆栈跟踪，并使正在运行的应用程序的内存转储和跟踪更易于理解。 但是，包括这些文件会导致部署捆绑包大小增加。

此属性是在 .NET SDK 7.0.100 中引入的，尽管它默认为未指定。

CopyDocumentationFilesFromPackages

将此属性设置为 true 时，将项目中 PackageReference 项的所有生成的 XML 文档文件复制到生成输出。 请注意，启用此功能将导致部署捆绑包大小增加。

此属性是在 .NET SDK 7.0.100 中引入的，尽管它默认为未指定。

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 Core 3.0 或更高版本的新 .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 部分。

EnableWindowsTargeting

将 EnableWindowsTargeting 属性设置为 true 以在非 Windows 平台上生成 Windows 应用（例如，Windows 窗体或 Windows Presentation Foundation 应用）。 如果未将此属性设置为 true，则会收到生成警告 NETSDK1100。 出现此错误的原因是不会在不支持的平台上自动下载目标包和运行时包。 通过设置此属性，这些包会在交叉目标时下载。

注意

当前建议使用此属性，以允许在非 Windows 平台上进行开发。 但是，当应用程序准备好发布时，它应在 Windows 上构建。 在非 Windows 平台上构建时，输出可能与在 Windows 上构建时不同。 具体而言，可执行文件不会标记为 Windows 应用程序（这意味着它将始终启动控制台窗口），并且不会嵌入图标。

<PropertyGroup>
  <EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

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>

DisableRuntimeMarshalling

使用该 DisableRuntimeMarshalling 属性，可以指定希望禁用对项目的运行时封送支持。 如果此属性设置为 true，则会将 DisableRuntimeMarshallingAttribute 添加到程序集，并且任何基于 P/Invokes 或基于委托的互操作将会遵循已禁用运行时封送的规则。

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</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 8，但不希望更改默认的代码分析规则集，请将 AnalysisLevel 设置为 7。

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

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

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

默认值：

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

下表显示可以指定的值。

值 含义
latest 使用已发布的最新版代码分析器。 这是默认值。
latest-<mode> 使用已发布的最新版代码分析器。 <mode> 值确定启用哪些规则。
preview 使用最新的代码分析器（即使它们处于预览状态）。
preview-<mode> 使用最新的代码分析器（即使它们处于预览状态）。 <mode> 值确定启用哪些规则。
8.0 即使有较新的规则可用，也会使用可用于 .NET 8 版本的规则集。
8.0-<mode> 即使有较新的规则可用，也会使用可用于 .NET 8 版本的规则集。 <mode> 值确定启用哪些规则。
8 即使有较新的规则可用，也会使用可用于 .NET 8 版本的规则集。
8-<mode> 即使有较新的规则可用，也会使用可用于 .NET 8 版本的规则集。 <mode> 值确定启用哪些规则。
7.0 即使有较新的规则可用，也会使用可用于 .NET 7 版本的规则集。
7.0-<mode> 即使有较新的规则可用，也会使用可用于 .NET 7 版本的规则集。 <mode> 值确定启用哪些规则。
7 即使有较新的规则可用，也会使用可用于 .NET 7 版本的规则集。
7-<mode> 即使有较新的规则可用，也会使用可用于 .NET 7 版本的规则集。 <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 6 开始，如果将 EnforceCodeStyleInBuild 设置为 true，此属性会影响代码样式 (IDEXXXX) 规则（以及代码质量规则）。
  • 如果为 AnalysisLevel 设置复合值，则无需指定 AnalysisMode。 但是，如果这样做，AnalysisLevel 会优先于 AnalysisMode。
  • 此属性对未引用项目 SDK 的项目（例如，引用 Microsoft.CodeAnalysis.NetAnalyzers NuGet 包的旧版 .NET Framework 项目）中的代码分析没有影响。

AnalysisLevel<Category>

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

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

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

值 说明
None 所有规则都处于禁用状态。 可以选择选择加入各条规则，以启用它们。
Default 默认模式是指某些规则作为生成警告启用；在该模式下，某些规则作为 Visual Studio IDE 建议启用，其余规则被禁用。
Minimum 比 Default 模式更主动的模式。 强烈建议生成实施的某些建议作为生成警告启用。 若要查看其中包含的规则，请检查 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig 文件。
Recommended 比 Minimum 模式更主动的模式，其中启用了更多规则作为生成警告。 若要查看其中包含的规则，请检查 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig 文件。
All 所有规则作为生成警告启用*。 可以选择选择退出各条规则，以禁用它们。

* 如果将 AnalysisMode 设置为 All，或者将 AnalysisLevel 设置为 latest-all，以下规则将不会启用：CA1017、CA1045、CA1005、CA1014、CA1060、CA1021 和代码指标分析器规则（CA1501、CA1502、CA1505、CA1506 和 CA1509）。 将来的版本可能会弃用这些旧规则。 但是，这些规则仍然可以通过使用 dotnet_diagnostic.CAxxxx.severity = <severity> 条目来单独启用。

注意

  • 从 .NET 6 开始，如果将 EnforceCodeStyleInBuild 设置为 true，此属性会影响代码样式 (IDEXXXX) 规则（以及代码质量规则）。
  • 如果使用 AnalysisLevel 的复合值（如 <AnalysisLevel>8-recommended</AnalysisLevel>），则可以完全省略此属性。 但是，如果同时指定这两个属性，则 AnalysisLevel 会优先于 AnalysisMode。
  • 此属性对未引用项目 SDK 的项目（例如，引用 Microsoft.CodeAnalysis.NetAnalyzers NuGet 包的旧版 .NET Framework 项目）中的代码分析没有影响。

AnalysisMode<Category>

此属性与 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>

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

_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 属性来配置某些运行时行为。 若要了解配置运行时行为的其他方法，请参阅运行时配置设置。

AutoreleasePoolSupport

AutoreleasePoolSupport 属性配置在受支持的 macOS 平台上运行时，每个托管线程是否接收隐式 NSAutoreleasePool。 有关详细信息，请参阅用于托管线程的 AutoreleasePool。

<PropertyGroup>
  <AutoreleasePoolSupport>true</AutoreleasePoolSupport>
</PropertyGroup>

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>

TieredPGO

TieredPGO 属性控制是否启用动态或分层的按配置优化 (PGO)。 要启用分层 PGO，请将值设置为 true。 有关详细信息，请参阅按配置优化。

<PropertyGroup>
  <TieredPGO>true</TieredPGO>
</PropertyGroup>

UseWindowsThreadPool

UseWindowsThreadPool 属性配置线程池线程管理是否委托给 Windows 线程池（仅限 Windows）。 默认值为 false，在这种情况下使用 .NET 线程池。 有关详细信息，请参阅 Windows 线程池。

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

DisableTransitiveFrameworkReferenceDownloads

将 DisableTransitiveFrameworkReferenceDownloads 属性设置为 true 以避免下载项目未直接引用的额外运行时包和目标包。

<PropertyGroup>
  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>

DisableTransitiveProjectReferences

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

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

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

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

ManagePackageVersionsCentrally

ManagePackageVersionsCentrally 属性是在 .NET 7 中引入的。 通过在存储库根目录的 Directory.Packages.props 文件中将其设置为 true，可以从一个位置管理项目中的常见依赖项。 使用 Directory.Packages.props 文件中的 PackageVersion 项为常见包依赖项添加版本。 然后，在各个项目文件中，可以从引用集中管理的包的任何 PackageReference 项中省略 Version 属性。

示例 Directory.Packages.props 文件：

<PropertyGroup>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
  <PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>

单个项目文件：

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>

有关详细信息，请参阅中央包管理 (CPM)。

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

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

UseMauiEssentials

将 UseMauiEssentials 属性设置为 true 以声明对依赖于 MAUI Essentials 的项目或包的显式引用。 此设置可确保项目拉取 MAUI Essentials 的正确已知框架引用。 如果项目引用了使用 MAUI Essentials 的项目，但未将此属性设置为 true，则可能会遇到生成警告 NETSDK1186。

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</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) 可用，则使用该密钥。 否则，不会向该特性添加公钥。

FrameworkReference

FrameworkReference 项定义对 .NET 共享框架的引用。

Include 属性指定框架 ID。

以下示例中的项目文件片段引用 Microsoft.AspNetCore.App 共享框架。

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

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> 指令。

项元数据

除了标准的 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 包含的文件在解决方案资源管理器中的显示方式。

Solution Explorer showing item with LinkBase metadata.

请参阅