Freigeben über

Kürzungsoptionen

  • Artikel

Die in diesem Artikel beschriebenen MSBuild-Eigenschaften und -Elemente beeinflussen das Verhalten von gekürzten, eigenständigen Bereitstellungen. Im Zusammenhang mit einigen Optionen wird ILLink erwähnt. Dies ist der Name des zugrunde liegenden Tools, das die Kürzung implementiert. Weitere Informationen zum zugrunde liegenden Tool finden Sie in der Trimmer-Dokumentation.

Das Kürzen mit PublishTrimmed wurde in .NET Core 3.0 eingeführt. Die anderen Optionen sind in .NET 5 und höheren Versionen verfügbar.

Aktivieren der Kürzung

  • <PublishTrimmed>true</PublishTrimmed>

    Aktivieren Sie die Kürzung während der Veröffentlichung. Diese Einstellung deaktiviert auch nicht kompatible Trim-Features und ermöglicht die Kürzungsanalyse während des Builds. In .NET 8 und höher-Apps ermöglicht diese Einstellung auch die Konfigurationsbindung und die Anforderung von Stellvertretungsquellengeneratoren.

Hinweis

Wenn Sie den Kürzungsvorgang als aktiviert in der Befehlszeile angeben, unterscheidet sich die Debugerfahrung, und es treten möglicherweise zusätzliche Fehler im Endprodukt auf.

Legen Sie diese Einstellung in der Projektdatei fest, um sicherzustellen, dass sie auch während dotnet build und nicht nur bei dotnet publish angewendet wird.

Diese Einstellung aktiviert das Kürzen und Kürzen aller Assemblys standardmäßig. In .NET 6 wurden standardmäßig nur Assemblys gekürzt, die sich für die Kürzung entschieden [AssemblyMetadata("IsTrimmable", "True")] haben (die in Projekten hinzugefügt wurden, die festgelegt <IsTrimmable>true</IsTrimmable>wurden). Über <TrimMode>partial</TrimMode> können Sie zum vorherigen Verhalten zurückkehren.

Dadurch werden alle Assemblys gekürzt, die für das Kürzen konfiguriert wurden. Beim Microsoft.NET.Sdk in .NET 6 werden alle Assemblys mit [AssemblyMetadata("IsTrimmable", "True")] eingeschlossen, also auch die .NET-Runtime-Assemblys. In .NET 5 werden Assemblys aus dem netcoreapp-Runtimepaket für die Kürzung über <IsTrimmable>-MSBuild-Metadaten konfiguriert. Andere SDKs definieren möglicherweise unterschiedliche Standardwerte.

Diese Einstellung aktiviert auch das Roslyn-Analysetool für Kürzungskompatibilität und deaktiviert Features, die nicht für die Kürzung geeignet sind.

Kürzungsgranularität

Verwenden Sie die TrimMode-Eigenschaft, um die Granularität beim Kürzen auf partial oder full festzulegen. Die Standardeinstellung für Konsolen-Apps (und ab .NET 8 auch Web SDK-Apps) ist full:

<TrimMode>full</TrimMode>

Um nur Assemblys zu kürzen, für die die Kürzung aktiviert wurde, legen Sie die Eigenschaft auf partial fest:

<TrimMode>partial</TrimMode>

Wenn Sie den Kürzungsmodus in partial ändern, können Sie einzelne Assemblys in das Kürzen einschließen, indem Sie das MSBuild-Element <TrimmableAssembly> verwenden.

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

Dies entspricht der Einstellung [AssemblyMetadata("IsTrimmable", "True")] beim Erstellen der Assembly.

Die folgenden Granularitätseinstellungen steuern, wie aggressiv nicht verwendete IL verworfen wird. Dies kann als Eigenschaft festgelegt werden, die sich auf alle Trimmereingabeassemblys auswirkt, oder als Metadaten für eine einzelne Assembly, die die Eigenschafteneinstellung überschreibt.

  • <TrimMode>link</TrimMode>

    Aktivieren Sie die Kürzung auf Memberebene, wodurch nicht verwendete Member aus Typen entfernt werden. Dies ist die Standardeinstellung in .NET 6 und höher.

  • <TrimMode>copyused</TrimMode>

    Aktivieren Sie das Kürzen auf Assemblyebene, wodurch die gesamte Assembly erhalten bleibt, wenn ein beliebiger Teil davon verwendet wird (im statischen Kontext).

Assemblys mit den Metadaten <IsTrimmable>true</IsTrimmable>, aber ohne expliziten TrimMode, verwenden den globalen TrimMode. Der Standardwert TrimMode für Microsoft.NET.Sdk ist link in .NET 6 und höher und copyused in früheren Versionen.

Kürzen zusätzlicher Assemblys

In .NET 6 und höher kürzt PublishTrimmed alle Assemblys mit dem folgenden Attribut auf Assemblyebene.

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

Die Frameworkbibliotheken verfügen über dieses Attribut. In .NET 6 und höher können Sie auch das Kürzen für eine Bibliothek ohne dieses Attribut verwenden, indem Sie die Assembly anhand des Namens (ohne .dll-Erweiterung) angeben.

Kürzen von Einstellungen für einzelne Assemblys

Beim Veröffentlichen einer gekürzten App berechnet das SDK ein ItemGroup-Element namens ManagedAssemblyToLink, das die Dateien darstellt, die für die Kürzung verarbeitet werden sollen. ManagedAssemblyToLink möglicherweise Metadaten, die das Kürzungsverhalten pro Assembly steuern. Erstellen Sie ein Ziel, das vor dem integrierten PrepareForILLink-Ziel ausgeführt wird, um diese Metadaten festzulegen. Das folgende Beispiel zeigt, wie Sie das Kürzen von MyAssembly aktivieren.

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

Sie können dieses Ziel auch verwenden, um das vom Bibliotheksautor angegebene Kürzungsverhalten außer Kraft zu setzen, indem <IsTrimmable>false</IsTrimmable> Sie für eine Assembly mit [AssemblyMetadata("IsTrimmable", "True"]).

Fügen Sie keine Elemente hinzu, oder entfernen Sie Elemente aus ManagedAssemblyToLink, da das SDK diesen Satz während der Veröffentlichung berechnet und erwartet, dass es sich nicht ändert. Folgende Metadaten werden unterstützt:

  • <IsTrimmable>true</IsTrimmable>

    Hiermit wird gesteuert, ob die angegebene Assembly gekürzt wird.

  • <TrimMode>copyused</TrimMode> oder <TrimMode>link</TrimMode>

    Hiermit wird die Kürzungsgranularität dieser Assembly gesteuert. Diese Metadaten haben Vorrang vor der globalen TrimMode. Das Festlegen von TrimMode für eine Assembly impliziert <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn>

    Steuern Sie, ob einzelne Warnungen für diese Assembly angezeigt werden sollen.

Stammassemblys

Wenn eine Assembly nicht gekürzt wird, wird sie als "root" betrachtet, was bedeutet, dass sie und alle ihre statisch verstandenen Abhängigkeiten beibehalten werden. Zusätzliche Assemblys können durch Namen (ohne Erweiterung .dll ) "root" sein:

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

Stammdeskriptoren

Eine andere Möglichkeit zum Angeben von Stämmen für die Analyse ist die Verwendung einer XML-Datei, die den Trimmer für das Deskriptorformat verwendet. Dies ermöglicht es Ihnen, bestimmte Member anstelle einer ganzen Assembly zu verwenden.

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

Beispielsweise kann eine bestimmte Methode stammen, MyRoots.xml auf die dynamisch von der Anwendung zugegriffen wird:

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

Analysewarnungen

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Aktivieren Sie Kürzungsanalysewarnungen.

Durch das Kürzen wird die IL entfernt, die nicht statisch erreichbar ist. Apps, die Spiegelung oder andere Muster verwenden, die dynamische Abhängigkeiten erstellen, können durch Kürzen unterbrochen werden. Um Warnungen zu solchen Mustern auszugeben, legen Sie <SuppressTrimAnalysisWarnings> auf false fest. Diese Einstellung zeigt Warnungen über die gesamte App an, einschließlich Ihres eigenen Codes, Bibliothekscodes und Frameworkcodes.

Roslyn-Analysetool

Wenn Sie PublishTrimmed in .NET 6 und höher festlegen, wird auch ein Roslyn-Analysetool aktiviert, das begrenzte Analysewarnungen anzeigt. Sie können das Analysetool auch unabhängig von PublishTrimmed aktivieren oder deaktivieren.

  • <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

    Aktivieren Sie ein Roslyn-Analysetool für eine Teilmenge der Kürzungsanalysewarnungen.

Unterdrücken von Warnungen

Sie können einzelne Warnungscodes mithilfe der üblichen MSBuild-Eigenschaften unterdrücken, die von der Toolkette berücksichtigt werden, darunter NoWarn, WarningsAsErrors, WarningsNotAsErrors und TreatWarningsAsErrors. Es gibt eine zusätzliche Option, die das ILLink-Warn-as-Error-Verhalten unabhängig voneinander steuert:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    Behandeln Sie ILLink-Warnungen nicht als Fehler. Dies kann hilfreich sein, um zu vermeiden, dass Warnungen zur Kürzung von Analysen in Fehler umgewandelt werden, wenn Compilerwarnungen global als Fehler behandelt werden.

Anzeigen ausführlicher Warnungen

In .NET 6 und höher wird bei der Kürzungsanalyse für jede Assembly, die aus einer PackageReference stammt, höchstens eine Warnung erzeugt, die angibt, dass die internen Daten der Assembly aus Kompatibilitätsgründen nicht gekürzt werden können. Sie können auch einzelne Warnungen für alle Assemblys anzeigen:

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

    Zeigen Sie alle detaillierten Warnungen an, anstatt sie auf eine einzelne Warnung pro Assembly zu reduzieren.

Entfernen von Symbolen

Symbole werden in der Regel gekürzt, damit sie mit den gekürzten Assemblys übereinstimmen. Sie können auch alle Symbole entfernen:

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    Entfernen Sie Symbole aus der gekürzten Anwendung einschließlich eingebetteter und separater PDB-Dateien. Dies gilt sowohl für den Anwendungscode als auch für alle Abhängigkeiten mit Symbolen.

Das SDK ermöglicht außerdem die Deaktivierung der Debuggerunterstützung mithilfe der Eigenschaft DebuggerSupport. Wenn die Debuggerunterstützung deaktiviert ist, entfernt das Kürzen automatisch Symbole (TrimmerRemoveSymbols wird standardmäßig auf "true" festgelegt).

Kürzen von Frameworkbibliotheksfeatures

Mehrere Featurebereiche der Frameworkbibliotheken enthalten Trimmeranweisungen, die es ermöglichen, den Code für deaktivierte Features zu entfernen.

MSBuild-Eigenschaft Beschreibung
AutoreleasePoolSupport Bei Festlegung auf false, entfernt Code, der Autorelease-Pools auf unterstützten Plattformen erstellt. false ist die Standardeinstellung für das .NET SDK.
DebuggerSupport Wenn diese Einstellung auf false" festgelegt ist , entfernt Code, der eine bessere Debugerfahrung ermöglicht. Durch diese Einstellung werden Symbole auch entfernt.
EnableUnsafeBinaryFormatterSerialization Wenn diese Option auf false"BinaryFormatter" festgelegt ist, wird die Serialisierungsunterstützung für BinaryFormatter entfernt. Weitere Informationen finden Sie unter BinaryFormatter serialization methods are obsolete and In-box BinaryFormatter implementation removed and always throws.
EnableUnsafeUTF7Encoding Bei Festlegung auf false, entfernt unsicheren UTF-7-Codierungscode. Weitere Informationen finden Sie unter UTF-7-Codepfade sind veraltet.
EventSourceSupport Bei Festlegung auf false, entfernt EventSource-bezogenen Code und Logik.
HttpActivityPropagationSupport Bei Festlegung auf false, entfernt Code im Zusammenhang mit der Diagnoseunterstützung für System.Net.Http.
InvariantGlobalization Bei Festlegung auf true, werden globalisierungsspezifischer Code und Daten entfernt. Weitere Informationen finden Sie unter Invarianter Modus.
MetadataUpdaterSupport Bei Festlegung auf false, entfernt Metadatenaktualisierungs-spezifische Logik im Zusammenhang mit dem hot reload.
MetricsSupport Wenn diese Einstellung auf false" festgelegt ist , wird die Unterstützung für System.Diagnostics.Metrics die Instrumentierung entfernt.
StackTraceSupport (.NET 8+) Bei Festlegung auf false, entfernt die Unterstützung für das Generieren von Stapelablaufverfolgungen (z. B Environment.StackTrace . oder Exception.ToString) durch die Laufzeit. Die Menge der Informationen, die aus Stapelablaufverfolgungszeichenfolgen entfernt werden, hängt möglicherweise von anderen Bereitstellungsoptionen ab. Diese Option wirkt sich nicht auf Stapelablaufverfolgungen aus, die von Debuggern generiert werden.
UseNativeHttpHandler Bei Festlegung auf true, verwendet die Standardplattformimplementierung für HttpMessageHandler Android und iOS und entfernt die verwaltete Implementierung.
UseSystemResourceKeys Wenn diese Einstellung auf true" festgelegt ist , werden Ausnahmemeldungen für System.* Assemblys entfernt. Wenn eine Ausnahme aus einer System.* Assembly ausgelöst wird, ist die Nachricht eine vereinfachte Ressourcen-ID anstelle der vollständigen Nachricht.
XmlResolverIsNetworkingEnabledByDefault (.NET 8+) Wenn diese Einstellung festgelegt falseist, wird die Unterstützung für das Auflösen von NICHT-Datei-URLs in System.Xmlentfernt. Es wird nur die Auflösung des Dateisystems unterstützt.

Diese Eigenschaften bewirken, dass der zugehörige Code gekürzt wird. Außerdem werden Features über die Datei runtimeconfig deaktiviert. Weitere Informationen zu diesen Eigenschaften einschließlich der entsprechenden runtimeconfig-Optionen finden Sie unter Featureoptionen. Einige SDKs weisen möglicherweise Standardwerte für diese Eigenschaften auf.

Bei der Kürzung deaktivierte Frameworkfeatures

Die folgenden Features sind mit dem Kürzen nicht kompatibel, da code erforderlich ist, auf den nicht statisch verwiesen wird. Diese Features sind in gekürzten Apps standardmäßig deaktiviert.

Warnung

Aktivieren Sie diese Features auf eigene Gefahr. Es ist wahrscheinlich, dass dadurch gekürzte Apps ohne zusätzlichen Aufwand zur Beibehaltung des dynamisch referenzierten Codes unterbrochen werden.

  • <BuiltInComInteropSupport>

    Die integrierte COM-Unterstützung ist deaktiviert.

  • <CustomResourceTypesSupport>

    Die Verwendung von benutzerdefinierten Ressourcentypen wird nicht unterstützt. Ressourcenmanager-Codepfade, die Spiegelung für benutzerdefinierte Ressourcentypen verwenden, werden gekürzt.

  • <EnableCppCLIHostActivation>

    Die C++/CLI-Hostaktivierung ist deaktiviert.

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    Die Verwendung der BinaryFormatter-Serialisierung durch DesigntimeLicenseContextSerializer ist deaktiviert.

  • <StartupHookSupport>

    Das Ausführen von Code vor dem Main Ausführen DOTNET_STARTUP_HOOKS von Code wird nicht unterstützt. Weitere Informationen finden Sie unter Hoststarthook.