剪裁选项

项目
2025-05-08

本文中所述的 MSBuild 属性和项会影响剪裁的自包含部署的行为。一些选项提及 ILLink，这是实现剪裁的基础工具的名称。有关基础工具的详细信息，请参阅剪裁器文档。

.NET Core 3.0 中引入了 PublishTrimmed 剪裁功能。其他选项在 .NET 5 及更高版本中可用。

启用剪裁

<PublishTrimmed>true</PublishTrimmed>

在发布期间启用剪裁。此设置还会关闭剪裁不兼容的功能，并在生成期间启用剪裁分析。在 .NET 8 及更高版本中，此设置还启用配置绑定和请求委托源生成器。

注意

如果将剪裁指定为从命令行启用，调试体验将有所不同，并且可能会在最终产品中遇到其他 bug。

将此设置放入项目文件中，以确保不只是在 dotnet build 期间，在 dotnet publish 期间也会应用该设置。

此设置还启用兼容剪裁的 Roslyn 分析器，并禁用不兼容剪裁的功能。

Roslyn 分析器

在 .NET 6 及更高版本中设置 PublishTrimmed 还将启用 Roslyn 分析器，该分析器仅显示有限的一组分析警告。还可独立于 PublishTrimmed 启用或禁用该分析器。

<EnableTrimAnalyzer>true</EnableTrimAnalyzer>

为一部分剪裁分析警告启用 Roslyn 分析器。

禁止显示警告

可以使用工具链遵循的常用 MSBuild 属性来取消单个警告代码，包括 NoWarn、WarningsAsErrors、WarningsNotAsErrors 和 TreatWarningsAsErrors。有一个附加选项可以独立控制 ILLink 警告错误行为：

<ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

请勿将 ILLink 警告视为错误。这可能有助于避免在全局将编译器警告视为错误时将剪裁分析警告转换为错误。

显示详细警告

在 .NET 6 及更高版本中，对于来自 PackageReference 的每个程序集，剪裁分析最多为其生成一个警告，以指示程序集的内部机制与剪裁功能不兼容。你还可显示所有程序集的各个警告：

<TrimmerSingleWarn>false</TrimmerSingleWarn>

显示所有详细警告，而不是将其折叠为每个程序集的单个警告。

删除符号

通常会对符号进行剪裁，以匹配剪裁的程序集。还可以删除所有符号：

<TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

删除剪裁后的应用程序中的符号，包括嵌入的 PDB 和单独的 PDB 文件。这同时适用于应用程序代码以及符号附带的任何依赖项。

SDK 还可使用属性 DebuggerSupport 来禁用调试器支持。禁用调试器支持后，剪裁会自动删除符号（TrimmerRemoveSymbols 默认为 true）。

剪裁框架库功能

框架库的一些功能区域随附有剪裁器指令，这些剪裁器指令可以删除已禁用功能的代码。

MSBuild 属性	说明
`AutoreleasePoolSupport`	设置为 `false`时，删除在受支持的平台上创建自动发布池的代码。 `false` 是 .NET SDK 的默认值。
`DebuggerSupport`	设置为 `false`时，删除支持更好的调试体验的代码。此设置还会删除符号。
`EnableUnsafeBinaryFormatterSerialization`	设置为 `false`时，删除 BinaryFormatter 序列化支持。有关详细信息，请参阅 BinaryFormatter 序列化方法已过时，并且已删除内置 BinaryFormatter 实现，并且始终引发。
`EnableUnsafeUTF7Encoding`	设置为 `false`后，删除不安全的 UTF-7 编码代码。有关详细信息，请参阅 UTF-7 代码路径已过时。
`EventSourceSupport`	设置为 `false`时，删除与 EventSource 相关的代码和逻辑。
`HttpActivityPropagationSupport`	设置为 `false`时，删除与诊断支持 System.Net.Http相关的代码。
`InvariantGlobalization`	设置为 `true`时，删除特定于全球化的代码和数据。有关详细信息，请参阅固定模式。
`MetadataUpdaterSupport`	设置为 “ `false`设置为”时，删除与热重载相关的元数据更新特定逻辑。
`MetricsSupport`	设置为 `false`时，删除对检测的支持 System.Diagnostics.Metrics 。
`StackTraceSupport` （.NET 8+）	设置为 `false`时，删除运行时生成堆栈跟踪（例如或 Environment.StackTrace Exception.ToString）的支持。从堆栈跟踪字符串中删除的信息量可能取决于其他部署选项。此选项不会影响调试器生成的堆栈跟踪。
`UseNativeHttpHandler`	设置为 `true`时，使用 Android 和 iOS 的默认平台实现 HttpMessageHandler 并删除托管实现。
`UseSystemResourceKeys`	设置为 `true`时，将去除程序集的 `System.` 异常消息。从 `System.` 程序集引发异常时，该消息是简化的资源 ID，而不是完整消息。
`XmlResolverIsNetworkingEnabledByDefault` （.NET 8+）	设置为 `false`时，将删除对解析非文件 URL System.Xml的支持。仅支持文件系统解析。

这些属性将导致剪裁相关代码，同时还将通过 runtimeconfig 文件禁用功能。有关这些属性（包括相应的 runtimeconfig 选项）的详细信息，请参阅功能切换。某些 SDK 可能具有这些属性的默认值。

剪裁时禁用的框架功能

以下功能与剪裁不兼容，因为它们需要不静态引用的代码。默认情况下，在剪裁的应用中禁用这些功能。

警告

启用这些功能的风险由你自担。这些功能可能会中断经过裁剪的应用，且不会执行任何操作来保留动态引用的代码。

<BuiltInComInteropSupport>

内置的 COM 支持已禁用。
<CustomResourceTypesSupport>

不支持使用自定义资源类型。剪裁使用自定义资源类型的反射的 ResourceManager 代码路径。
<EnableCppCLIHostActivation>

C++/CLI 主机激活已禁用。
<EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

禁止 DesigntimeLicenseContextSerializer 使用 BinaryFormatter 序列化。
<StartupHookSupport>

不支持之前MainDOTNET_STARTUP_HOOKS运行代码。有关详细信息，请参阅主机启动挂钩。

通过