修剪選項

下列 MSBuild 屬性和專案會影響 修剪的自封式部署行為。 有些選項提及 ILLink ,這是實作修剪的基礎工具名稱。 如需基礎工具的詳細資訊,請參閱 修剪器檔

PublishTrimmed .NET Core 3.0 中引進了 修剪 。 其他選項僅適用于 .NET 5 和更新版本。

啟用修剪

  • <PublishTrimmed>true</PublishTrimmed>

    在發佈期間啟用修剪。 這也會關閉修剪不相容的功能,並在建置期間啟用 修剪分析

將此設定放在專案檔中,以確保設定會在 期間 dotnet build 套用,而不只是 dotnet publish

此設定會啟用修剪,而且預設會修剪所有元件。 在 .NET 6 中,預設只會修剪加入宣告修剪的 [AssemblyMetadata("IsTrimmable", "True")] 元件。 您可以使用 返回先前的行為 <TrimMode>partial</TrimMode>

此設定會修剪已設定為修剪的任何元件。 在 Microsoft.NET.Sdk .NET 6 中,這包括具有 [AssemblyMetadata("IsTrimmable", "True")] 的任何元件,這是 .NET 執行時間元件的情況。 在 .NET 5 中,netcoreapp 執行時間套件中的元件會設定為透過 <IsTrimmable> MSBuild 中繼資料進行修剪。 其他 SDK 可能會定義不同的預設值。

此設定也會啟用修剪相容性 Roslyn 分析器 ,並停用 與修剪不相容的功能

修剪資料細微性

預設值是修剪應用程式中的所有元件。 這可以使用 屬性來變更 TrimMode

若要只修剪已加入宣告修剪的元件,請將 屬性設定為 partial

<TrimMode>partial</TrimMode>

預設設定為 full

<TrimMode>full</TrimMode>

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

  • <TrimMode>link</TrimMode>

    啟用成員層級修剪,這會從類型中移除未使用的成員。 這是 .NET 6+ 中的預設值。

  • <TrimMode>copyused</TrimMode>

    啟用元件層級修剪,如果元件的任何部分使用 (靜態理解的方式) ,則會保留整個元件。

具有 <IsTrimmable>true</IsTrimmable> 中繼資料但未明確 TrimMode 使用的元件會使用全域 TrimMode 。 的預設值 TrimModeMicrosoft.NET.Sdklink .NET 6+ 和 copyused 舊版。

修剪其他元件

在 .NET 6+ 中, PublishTrimmed 使用下列元件層級屬性修剪元件:

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

架構程式庫具有此屬性。 在 .NET 6+ 中,您也可以選擇在沒有此屬性的情況下修剪程式庫,並依名稱指定元件, (而不 .dll 使用副檔名) 。

在 .NET 7 中, <TrimMode>full</TrimMode> 是預設值,但如果您將修剪模式變更為 partial ,則可以加入宣告個別元件來修剪。

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

這相當於在建置元件時進行設定 [AssemblyMetadata("IsTrimmable", "True")]

修剪個別元件的設定

發佈修剪的應用程式時,SDK 會 ItemGroup 計算名為 ManagedAssemblyToLink 的 ,代表要處理以進行修剪的檔案集。 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><TrimmerSingleWarn>False</TrimmerSingleWarn>

    控制是否要顯示這個元件的 單一警告

根元件

如果未修剪元件,則會將其視為「rooted」,這表示會保留它及其所有靜態瞭解相依性。 其他元件可能會依名稱 (「根」,而不需 .dll 副檔名) :

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

根描述項

另一個指定根分析的方法,是使用使用修剪器 描述元格式的 XML 檔案。 這可讓您根目錄特定成員,而不是整個元件。

<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 屬性來隱藏個別 警告碼 ,包括 NoWarnWarningsAsErrorsWarningsNotAsErrorsTreatWarningsAsErrors 。 另外還有一個選項可獨立控制 ILLink 警告即錯誤行為:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    請勿將 ILLink 警告視為錯誤。 當將編譯器警告視為全域錯誤時,這可能有助於避免將分析警告轉換成錯誤。

顯示詳細的警告

在 .NET 6+ 中,修剪分析會針對來自 PackageReference 的每個元件產生最多一個警告,表示元件的內部元件與修剪不相容。 您也可以顯示所有元件的個別警告:

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

    顯示所有詳細的警告,而不是將它們折迭成每個元件的單一警告。

移除符號

符號通常會修剪以符合修剪的元件。 您也可以移除所有符號:

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    從修剪的應用程式移除符號,包括內嵌 PDB 和個別的 PDB 檔案。 這同時適用于應用程式程式碼和任何隨附符號的相依性。

SDK 也可讓您使用 屬性 DebuggerSupport 來停用偵錯工具支援。 停用偵錯工具支援時,修剪會自動移除符號, (TrimmerRemoveSymbols 預設為 true) 。

修剪架構程式庫功能

架構程式庫的數個功能區域隨附修剪器指示詞,可讓您移除已停用功能的程式碼。

  • <AutoreleasePoolSupport>false</AutoreleasePoolSupport> (預設)

    移除在支援平臺上建立自動發行集區的程式碼。 請參閱 Managed 執行緒的 AutoreleasePool。 這是 .NET SDK 的預設值。

  • <DebuggerSupport>false</DebuggerSupport>

    移除可提供更好的偵錯體驗的程式碼。 此設定也會 移除符號

  • <EnableUnsafeBinaryFormatterSerialization>false</EnableUnsafeBinaryFormatterSerialization>

    移除 BinaryFormatter 序列化支援。 如需詳細資訊,請參閱 BinaryFormatter 序列化方法已過時

  • <EnableUnsafeUTF7Encoding>false</EnableUnsafeUTF7Encoding>

    移除不安全的 UTF-7 編碼程式碼。 如需詳細資訊,請參閱 UTF-7 程式碼路徑已過時

  • <EventSourceSupport>false</EventSourceSupport>

    移除 EventSource 相關程式碼或邏輯。

  • <HttpActivityPropagationSupport>false</HttpActivityPropagationSupport>

    移除與 System.Net.Http 診斷支援相關的程式碼。

  • <InvariantGlobalization>true</InvariantGlobalization>

    移除全球化特定的程式碼和資料。 如需詳細資訊,請參閱 非變異模式

  • <MetadataUpdaterSupport>false</MetadataUpdaterSupport>

    移除與熱重載相關的中繼資料更新特定邏輯。

  • <UseNativeHttpHandler>true</UseNativeHttpHandler>

    使用適用于 Android/iOS 的 HttpMessageHandler 的預設平臺實作,並移除 Managed 實作。

  • <UseSystemResourceKeys>true</UseSystemResourceKeys>

    元件的等 System.* 量例外狀況訊息。 從 System.* 元件擲回例外狀況時,訊息會是簡化的資源識別碼,而不是完整訊息。

這些屬性會導致修剪相關的程式碼,並透過 runtimeconfig 檔案停用功能。 如需這些屬性的詳細資訊,包括對應的 Runtimeconfig 選項,請參閱 功能參數。 某些 SDK 可能會有這些屬性的預設值。

修剪時停用的架構功能

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

警告

以您自己的風險啟用這些功能。 它們可能會中斷修剪的應用程式,而不需要額外的工作來保留動態參考的程式碼。

  • <BuiltInComInteropSupport>

    已停用內建 COM 支援。

  • <CustomResourceTypesSupport>

    不支援使用自訂資源類型。 會修剪針對自訂資源類型使用反映的 ResourceManager 程式碼路徑。

  • <EnableCppCLIHostActivation>

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

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    DesigntimeLicenseContextSerializer 停用串列 BinaryFormatter 化的使用。

  • <StartupHookSupport>

    不支援在 之前 Main 執行程式 DOTNET_STARTUP_HOOKS 代碼。 如需詳細資訊,請參閱 主機啟動攔截