調整選項
下列 MSBuild 屬性和項目,會影響調整的獨立式部署行為。 其中一些選項提及 ILLink
,其為實作調整的基礎工具名稱。 如需基礎工具的詳細資訊,請參閱修剪器文件 (英文)。
之前 .NET Core 3.0 推出了透過 PublishTrimmed
進行調整。 而其他選項則只有在 .NET 5 和更新版本中才提供。
啟用調整
<PublishTrimmed>true</PublishTrimmed>
啟用發佈期間進行調整。 如此也會關閉與調整不相容的功能,並會在建置期間啟用調整分析 。
注意
如果您從命令列指定會啟用調整,則偵錯體驗將會有所不同,而且在最終產品中,可能會遇到其他 bug。
將此設定置於專案檔中,可確保 dotnet build
期間 (而不只是 dotnet publish
期間),都會套用該設定。
此設定會啟用調整,且預設會調整所有組件。 在 .NET 6 中,預設只會調整選擇要經由 [AssemblyMetadata("IsTrimmable", "True")]
進行調整的組件。 使用 <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>
您也可以使用它來覆寫程式庫作者所指定的調整行為,方法是利用 [AssemblyMetadata("IsTrimmable", "True"])
為組件設定 <IsTrimmable>false</IsTrimmable>
。
請勿對 ManagedAssemblyToLink
新增或移除項目,因為 SDK 在發佈期間,會計算此設定,而且希望它不要變更。 支援的中繼資料為:
根組件
如果組件未調整,就會將其視為 "root" 了,表示將會保留它及其所有靜態了解的相依性。 其他組件可依名稱 "root" (不含 .dll
延伸模組):
<ItemGroup>
<TrimmerRootAssembly Include="MyAssembly" />
</ItemGroup>
Root 描述元
另一種指定根以進行分析的方式,是利用使用修剪器描述元格式的 XML 檔案。 您可利用此方式,Root 特定的成員,而非整個組件。
<ItemGroup>
<TrimmerRootDescriptor Include="MyRoots.xml" />
</ItemGroup>
例如,MyRoots.xml
可能會 Root 一個應用程式會動態存取的特定方法:
<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)。
調整架構程式庫功能
架構程式庫的數個功能區域,有修剪器的指示詞,可讓您能移除已停用功能的程式碼。
<AutoreleasePoolSupport>false</AutoreleasePoolSupport>
(預設值)移除在支援平台上建立自動發行集區的程式碼。 請參閱受控執行緒的 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>
移除與熱重新載入相關的中繼資料更新專用邏輯。
<StackTraceSupport>false</StackTraceSupport>
(.NET 8+)移除執行階段產生堆疊追蹤的支援 (例如 Environment.StackTrace 或 Exception.ToString)。 從堆疊追蹤字串中移除的資訊量可能取決於其他部署選項。 此選項不會影響偵錯工具所產生的堆疊追蹤。
<UseNativeHttpHandler>true</UseNativeHttpHandler>
使用適用於 Android/iOS 的 HttpMessageHandler 的預設平台實作,並移除受控實作。
<UseSystemResourceKeys>true</UseSystemResourceKeys>
移除
System.*
組件的例外狀況訊息。 從System.*
組件擲回例外狀況時,訊息會是簡化的資源識別碼,而非完整的訊息。
這些屬性會讓相關的程式碼進行調整,也會透過 runtimeconfig 檔案,停用一些功能。 如需這些屬性的詳細資訊,包括對應的 runtimeconfig 選項,請參閱 功能參數 (英文)。 某些 SDK 可能有這些屬性的預設值。
調整時停用的架構功能
下列功能與調整不相容,因為這些功能需要非靜態參考的程式碼。 在已調整的應用程式中,這些會預設為停用。
警告
自行啟用這些功能,風險自負。 它們很可能會中斷調整的應用程式,而不需要額外的工作即可保留動態參考的程式碼。
<BuiltInComInteropSupport>
內建 COM 支援已停用。
<CustomResourceTypesSupport>
不支援使用自訂資源類型。 為自訂資源類型使用反射的 ResourceManager 程式碼路徑,會進行調整。
<EnableCppCLIHostActivation>
C++/CLI 主機啟用已停用。
<EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>
DesigntimeLicenseContextSerializer 使用
BinaryFormatter
序列化的功能已停用。<StartupHookSupport>
不支援在
Main
之前以DOTNET_STARTUP_HOOKS
執行程式碼。 如需詳細資訊,請參閱主機啟動勾點。
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應