Share via

Kürzungsoptionen

  • Artikel

Die folgenden 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 nur 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 [AssemblyMetadata("IsTrimmable", "True")] entschieden haben. Ü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.

  • <AutoreleasePoolSupport>false</AutoreleasePoolSupport> (Standard)

    Entfernen Sie Code, der Pools für die automatische Freigabe auf unterstützten Plattformen erstellt. Informationen dazu finden Sie unter AutoreleasePool für verwaltete Threads. Dies ist die Standardeinstellung für das .NET SDK.

  • <DebuggerSupport>false</DebuggerSupport>

    Hiermit entfernen Sie Code, um das Debuggen verbessern zu können. Durch diese Einstellung werden Symbole auch entfernt.

  • <EnableUnsafeBinaryFormatterSerialization>false</EnableUnsafeBinaryFormatterSerialization>

    Hiermit entfernen Sie die BinaryFormatter-Serialisierungsunterstützung. Weitere Informationen finden Sie unter BinaryFormatter-Serialisierungsmethoden sind veraltet und in ASP.NET-Apps verboten.

  • <EnableUnsafeUTF7Encoding>false</EnableUnsafeUTF7Encoding>

    Hiermit wird unsicherer UTF-7-Codierungscode entfernt. Weitere Informationen finden Sie unter UTF-7-Codepfade sind veraltet.

  • <EventSourceSupport>false</EventSourceSupport>

    Hiermit entfernen Sie Code oder Logik, der bzw. die mit EventSource verknüpft ist.

  • <HttpActivityPropagationSupport>false</HttpActivityPropagationSupport>

    Hiermit entfernen Sie Code, der im Zusammenhang mit der Diagnoseunterstützung für System.Net.Http steht.

  • <InvariantGlobalization>true</InvariantGlobalization>

    Hiermit entfernen Sie globalisierungsspezifischen Code und globalisierungsspezifische Daten. Weitere Informationen finden Sie unter Invarianter Modus.

  • <MetadataUpdaterSupport>false</MetadataUpdaterSupport>

    Entfernen Sie spezifische Logik zum Aktualisieren von Metadaten im Zusammenhang mit Hot Reload.

  • <StackTraceSupport>false</StackTraceSupport> (.NET 8+)

    Unterstützung für das Generieren von Stapelablaufverfolgungen (z. B. Environment.StackTrace oder Exception.ToString) nach der Laufzeit entfernt. Der Umfang der Informationen, die aus den Stapelablaufverfolgungszeichenfolgen entfernt werden, kann von anderen Einsatzoptionen abhängen. Diese Option wirkt sich nicht auf Stapelablaufverfolgungen aus, die von Debuggern generiert werden.

  • <UseNativeHttpHandler>true</UseNativeHttpHandler>

    Verwenden Sie die standardmäßige Plattformimplementierung von HttpMessageHandler für Android/iOS, und entfernen Sie die verwaltete Implementierung.

  • <UseSystemResourceKeys>true</UseSystemResourceKeys>

    Entfernen Sie Ausnahmemeldungen für System.*-Assemblys. Wenn eine Ausnahme aus einer System.* Assembly ausgelöst wird, ist die Nachricht eine vereinfachte Ressourcen-ID anstelle der vollständigen Nachricht.

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.