調整選項

  • 發行項

本文所述的 MSBuild 屬性和專案會影響修剪、獨立式部署的行為。 其中一些選項提及 ILLink，其為實作調整的基礎工具名稱。 如需基礎工具的詳細資訊，請參閱修剪器文件 (英文)。

之前 .NET Core 3.0 推出了透過 PublishTrimmed 進行調整。 其他選項適用於 .NET 5 和更新版本。

啟用調整

  • <PublishTrimmed>true</PublishTrimmed>

    啟用發佈期間進行調整。 此設定也會關閉 trim-incompatible 功能，並在建置期間啟用 修剪分析 。 在 .NET 8 和更新版本中，此設定也會啟用組態系結和要求委派來源產生器。

注意

如果您將修剪指定為從命令行啟用，您的偵錯體驗將會有所不同，而且您在最終產品中可能會遇到其他錯誤。

將此設定置於專案檔中，可確保 dotnet build 期間 (而不只是 dotnet publish 期間)，都會套用該設定。

此設定預設會啟用修剪和修剪所有元件。 在 .NET 6 中，預設只會修剪選擇透過 修剪 [AssemblyMetadata("IsTrimmable", "True")] 的元件（在已設定 <IsTrimmable>true</IsTrimmable>的專案中新增）。 使用 <TrimMode>partial</TrimMode> 可以返回先前的行為。

此設定會調整已設定為要調整的所有組件。 .NET 6 中的 Microsoft.NET.Sdk，這包括具有 [AssemblyMetadata("IsTrimmable", "True")] 的所有組件，也就是 .NET 執行階段組件的情況。 在 .NET 5 中，來自 netcoreapp 執行階段套件中的組件，會設定為透過 <IsTrimmable> MSBuild 中繼資料進行調整。 其他 SDK 可能會定義不同的預設值。

此設定也會啟用調整相容性 Roslyn 分析器，並會停用與調整不相容的功能。

調整細微度

使用 TrimMode 屬性將調整細微性設定為 partial 或 full。 主控應用程式 (以及從 .NET 8 開始，Web SDK 應用程式) 的預設設定為 full：

<TrimMode>full</TrimMode>

若要只調整已選擇要進行調整的組件，請將屬性設定為 partial：

<TrimMode>partial</TrimMode>

如果將調整模式變更為 partial，則可透過使用 <TrimmableAssembly> MSBuild 項目選擇要調整的個別組件。

<ItemGroup>
  <TrimmableAssembly Include="MyAssembly" />
</ItemGroup>

這相當於在建置組件時，設定 [AssemblyMetadata("IsTrimmable", "True")]。

下列細微度設定，可控制捨棄未使用 IL 的積極度。 這可以設定為會影響所有修剪器輸入組件的屬性，或設定為個別組件上的中繼資料，覆寫該屬性的設定。

  • <TrimMode>link</TrimMode>

    啟用成員層級調整，會從各類型中移除未使用的成員。 這是 .NET 6+ 中的預設值。

  • <TrimMode>copyused</TrimMode>

    啟用組件層級調整，會在使用任一部分的組件時，保留整個組件 (以靜態方式了解)。

具有 <IsTrimmable>true</IsTrimmable> 中繼資料但未明確 TrimMode 的組件，會使用全域 TrimMode。 Microsoft.NET.Sdk 的預設 TrimMode 為 link (.NET 6+) 和 copyused (舊版)。

調整其他組件

在 .NET 6+ 中，PublishTrimmed 使用下列組件層級屬性來修剪組件：

[AssemblyMetadata("IsTrimmable", "True")]

架構程式庫有這個屬性。 在 .NET 6+ 中，您也可以選擇在調整程式庫時不指定此屬性，而依名稱指定組件 (不含 .dll 延伸模組)。

調整個別組件的設定

發佈調整過的應用程式時，SDK 會計算一個稱為 ManagedAssemblyToLink 的 ItemGroup，代表要處理以進行調整的一組檔案。 ManagedAssemblyToLink 可能有可控制每個元件的修剪行為的元數據。 若要設定此中繼資料，請建立一個在內建 PrepareForILLink 目標之前，先執行的目標。 下列範例示範如何為 MyAssembly 啟用調整。

<Target Name="ConfigureTrimming"
        BeforeTargets="PrepareForILLink">
  <ItemGroup>
    <ManagedAssemblyToLink Condition="'%(Filename)' == 'MyAssembly'">
      <IsTrimmable>true</IsTrimmable>
    </ManagedAssemblyToLink>
  </ItemGroup>
</Target>

您也可以使用這個目標來覆寫連結庫作者所指定的修剪行為，方法是使用 設定 <IsTrimmable>false</IsTrimmable> 元件 [AssemblyMetadata("IsTrimmable", "True"])。

請勿從 ManagedAssemblyToLink新增或移除專案，因為 SDK 會在發布期間計算此集合，並預期不會變更。 支援的中繼資料為：

  • <IsTrimmable>true</IsTrimmable>

    控制是否調整指定的組件。

  • <TrimMode>copyused</TrimMode> 或 <TrimMode>link</TrimMode>

    控制此組件的調整細微度。 此元資料的優先順序高於全域 TrimMode。 在組件上設定 TrimMode，也就是表示 <IsTrimmable>true</IsTrimmable>。

  • <TrimmerSingleWarn>True</TrimmerSingleWarn>

    控制是否要顯示此組件的單一警告。

根組件

如果未修剪元件，則會將其視為「rooted」，這表示會保留它及其所有靜態瞭解的相依性。 其他元件可以依名稱「根」（不含 .dll 延伸模組）：

<ItemGroup>
  <TrimmerRootAssembly Include="MyAssembly" />
</ItemGroup>

Root 描述元

另一種指定根以進行分析的方式，是利用使用修剪器描述元格式的 XML 檔案。 您可利用此方式，Root 特定的成員，而非整個組件。

<ItemGroup>
  <TrimmerRootDescriptor Include="MyRoots.xml" />
</ItemGroup>

例如， MyRoots.xml 可能會根目錄為應用程式動態存取的特定方法：

<linker>
  <assembly fullname="MyAssembly">
    <type fullname="MyAssembly.MyClass">
      <method name="DynamicallyAccessedMethod" />
    </type>
  </assembly>
</linker>

分析警告

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    啟用調整分析警告。

修剪會移除無法靜態存取的 IL。 使用反映或其他建立動態相依性模式的應用程式，可能會因修剪而中斷。 若要警告出現這類模式，請將 <SuppressTrimAnalysisWarnings> 設定為 false。 此設定會顯示整個應用程式的警告，包括您自己的程式代碼、連結庫程式碼和架構程序代碼。

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 作，並移除Managed實作。
UseSystemResourceKeys 當設定為 true時，會移除元件的例外狀況訊息 System.* 。 從元件擲回 System.* 例外狀況時，訊息是簡化的資源標識符，而不是完整訊息。
XmlResolverIsNetworkingEnabledByDefault (.NET 8+) 當 設定為 false時，會移除 在 中 System.Xml解析非檔案 URL 的支援。 僅支援檔案系統解析。

這些屬性會讓相關的程式碼進行調整，也會透過 runtimeconfig 檔案，停用一些功能。 如需這些屬性的詳細資訊，包括對應的 runtimeconfig 選項，請參閱 功能參數 (英文)。 某些 SDK 可能具有這些屬性的預設值。

調整時停用的架構功能

下列功能與修剪不相容，因為它們需要未以靜態方式參考的程序代碼。 在修剪的應用程式中，這些功能預設為停用。

警告

自行啟用這些功能，風險自負。 它們很可能會中斷調整的應用程式，而不需要額外的工作即可保留動態參考的程式碼。

  • <BuiltInComInteropSupport>

    內建 COM 支援已停用。

  • <CustomResourceTypesSupport>

    不支援使用自定義資源類型。 會修剪使用反映自定義資源類型的 ResourceManager 程式代碼路徑。

  • <EnableCppCLIHostActivation>

    C++/CLI 主機啟用已停用。

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    DesigntimeLicenseContextSerializer 使用 BinaryFormatter 序列化的功能已停用。

  • <StartupHookSupport>

    不支援使用 之前MainDOTNET_STARTUP_HOOKS執行程序代碼。 如需詳細資訊，請參閱主機啟動勾點。