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. Dadurch werden außerdem Features deaktiviert, die nicht für die Kürzung geeignet sind, und die Kürzungsanalyse während der Erstellung aktiviert.

Hinweis

Wenn Sie die Kürzung über die Befehlszeile aktivieren, unterscheidet sich die Debuggingfunktionalität, und es können zusätzliche Fehler im endgültigen Produkt auftreten.

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 ermöglicht die Kürzung und kürzt standardmäßig alle Assemblys. In .NET 6 werden standardmäßig nur Assemblys gekürzt, die die Kürzung über [AssemblyMetadata("IsTrimmable", "True")] aktiviert 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 andere 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 kann über Metadaten verfügen, 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 dies auch verwenden, um das vom Bibliotheksautor angegebene Kürzungsverhalten außer Kraft zu setzen, indem Sie <IsTrimmable>false</IsTrimmable> für eine Assembly mit [AssemblyMetadata("IsTrimmable", "True"]) festlegen.

Fügen Sie ManagedAssemblyToLink keine Elemente hinzu, oder entfernen Sie keine Elemente, da das SDK diese Gruppe während der Veröffentlichung berechnet und davon ausgeht, dass nichts geändert wird. 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 hat Vorrang vor dem globalen TrimMode. Das Festlegen von TrimMode für eine Assembly impliziert <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn> oder <TrimmerSingleWarn>False</TrimmerSingleWarn>

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

Stammassemblys

Eine nicht gekürzte Assembly wird als Stammassembly betrachtet, was bedeutet, dass sie und alle statisch interpretierten Abhängigkeiten beibehalten werden. Zusätzliche Assemblys können je nach Name zu Stammassemblys werden (ohne die Erweiterung .dll):

<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 MyRoots.xml eine bestimmte Methode sein, auf die die Anwendung dynamisch zugreift:

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

Analysewarnungen

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Aktivieren Sie Kürzungsanalysewarnungen.

Durch die Kürzung wird die IL entfernt, die statisch nicht erreichbar ist. Apps, die Reflexion oder andere Muster verwenden, die die dynamischen Abhängigkeiten erstellen, können durch das Kürzen beschädigt werden. Um Warnungen zu solchen Mustern auszugeben, legen Sie <SuppressTrimAnalysisWarnings> auf false fest. Dies schließt Warnungen zur gesamten App ein, 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, mit der das ILLink-Verhalten zum Warnen vor Fehlern unabhängig gesteuert wird:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    Behandeln Sie ILLink-Warnungen nicht als Fehler. Dies kann hilfreich sein, um zu vermeiden, dass Kürzungsanalysewarnungen zu Fehlern 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, werden Symbole durch die Kürzung automatisch entfernt (TrimmerRemoveSymbols wird standardmäßig „true“).

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 von 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 verfügen möglicherweise über Standardwerte für diese Eigenschaften.

Bei der Kürzung deaktivierte Frameworkfeatures

Die folgenden Features sind nicht mit Kürzungen kompatibel, da sie Code erfordern, auf den nicht statisch verwiesen wird. Diese 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 benutzerdefinierter Ressourcentypen wird nicht unterstützt. ResourceManager-Codepfade, die Reflektion 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 Main mit DOTNET_STARTUP_HOOKS wird nicht unterstützt. Weitere Informationen finden Sie unter Hoststarthook.