Kürzen einer .NET MAUI-App

Wenn sie Ihre App erstellt, kann .NET Multi-Platform App UI (.NET MAUI) einen Linker verwenden, der aufgerufen ILLink wird, um die Gesamtgröße der App mit einer Technik zu verringern, die als Kürzen bezeichnet wird. ILLink reduziert die Größe, indem der vom Compiler erzeugte Zwischencode analysiert wird. Es entfernt nicht verwendete Methoden, Eigenschaften, Felder, Ereignisse, Strukturen und Klassen, um eine App zu erstellen, die nur Code und Assembly-Abhängigkeiten enthält, die für die Ausführung der App erforderlich sind.

Um Änderungen des Verhaltens beim Kürzen von Apps zu verhindern, stellt .NET statische Analysen zur Kürzung der Kompatibilität durch Kürzungswarnungen bereit. Der Kürzer erzeugt Kürzungswarnungen, wenn er Code findet, der möglicherweise beim Kürzen nicht kompatibel ist. Wenn es Warnungen zu Kürzen gibt, sollten sie behoben werden, und die App sollte nach dem Kürzen gründlich getestet werden, um sicherzustellen, dass keine Verhaltensänderungen vorhanden sind. Weitere Informationen finden Sie in der Einführung zum Kürzen von Warnungen.

Kürzungsverhalten

Das Kürzungsverhalten kann gesteuert werden, indem die $(TrimMode) Buildeigenschaft entweder partial oder full:

<PropertyGroup>
  <TrimMode>full</TrimMode>
</PropertyGroup>

Der full Kürzungsmodus entfernt code, der von Ihrer App nicht verwendet wird. Der partial Zuschneidemodus schneidet die Basisklassenbibliothek (BCL), Assemblys für die zugrunde liegenden Plattformen (z. B. Mono.Android.dll und Microsoft.iOS.dll) und alle anderen Assemblys, die sich für die Kürzung mit dem $(TrimmableAsssembly) Buildelement entschieden haben:

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

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

Weitere Kürzungsoptionen finden Sie unter "Trimming"-Optionen.

Standardeinstellungen für das Kürzen

Standardmäßig verwenden Android- und Mac Catalyst-Builds teilkürzungen, wenn die Buildkonfiguration auf einen Releasebuild festgelegt ist. iOS verwendet partielles Kürzen für alle Gerätebuilds, unabhängig von der Buildkonfiguration und verwendet keine Kürzung für Simulatorbuilds.

Kürzen von Inkompatibilitäten

Die folgenden .NET MAUI-Features sind nicht mit vollständiger Kürzung kompatibel und werden vom Trimmer entfernt:

• Bindungsausdrücke, bei denen dieser Bindungspfad auf eine Zeichenfolge festgelegt ist. Verwenden Sie stattdessen kompilierte Bindungen. Für weitere Informationen siehe Kompilierte Bindungen.
• Implizite Konvertierungsoperatoren beim Zuweisen eines Werts eines inkompatiblen Typs zu einer Eigenschaft in XAML oder wenn zwei Eigenschaften unterschiedlicher Typen eine Datenbindung verwenden. Stattdessen sollten Sie einen TypeConverter für Ihren Typ definieren und ihn mithilfe des TypeConverterAttributeTyps anfügen. Weitere Informationen finden Sie unter Define a TypeConverter to replace an implicit conversion operator.
• Laden von XAML zur Laufzeit mit der LoadFromXaml Erweiterungsmethode. Dieser XAML-Code kann durch Kommentieren aller Typen, die zur Laufzeit mit dem DynamicallyAccessedMembers Attribut oder dem DynamicDependency Attribut geladen werden können, sicher gekürzt werden. Dies ist jedoch sehr fehleranfällig und wird nicht empfohlen.
• Empfangen von Navigationsdaten mithilfe der QueryPropertyAttribute. Stattdessen sollten Sie die IQueryAttributable Schnittstelle für Typen implementieren, die Abfrageparameter akzeptieren müssen. Weitere Informationen finden Sie unter Verarbeiten von Navigationsdaten mit einer einzelnen Methode.
• Die SearchHandler.DisplayMemberName-Eigenschaft Stattdessen sollten Sie ein ItemTemplate bereitstellen, um das Erscheinungsbild der SearchHandler-Ergebnisse zu definieren. Weitere Informationen finden Sie unter Definieren der Darstellung von Suchergebnissen.
• Das HybridWebView Steuerelement wird aufgrund seiner Verwendung dynamischer System.Text.Json Serialisierungsfeatures verwendet.
• UI-Anpassung mit der OnPlatform XAML-Markuperweiterung. Stattdessen sollten Sie die OnPlatform<T>-Klasse verwenden. Weitere Informationen finden Sie unter Anpassen der UI-Darstellung basierend auf der Plattform.
• UI-Anpassung mit der OnIdiom XAML-Markup-Erweiterung. Stattdessen sollten Sie die OnIdiom<T>-Klasse verwenden. Weitere Informationen finden Sie unter Anpassen der Ui-Darstellung basierend auf dem Gerätediom.

Alternativ können Sie Featureoptionen verwenden, damit der Trimmer den Code für diese Features behält. Weitere Informationen finden Sie unter "Trimming feature switches".

Informationen zu .NET-Kürzungsinkompatibilitäten finden Sie unter "Bekannte Kürzungsinkompatibilitäten".

Definieren eines TypeConverter-Elements zum Ersetzen eines impliziten Konvertierungsoperators

Es ist nicht möglich, beim Zuweisen eines Werts eines inkompatiblen Typs zu einer Eigenschaft in XAML auf implizite Konvertierungsoperatoren zu vertrauen, oder wenn zwei Eigenschaften unterschiedlicher Typen eine Datenbindung verwenden, wenn die vollständige Kürzung aktiviert ist. Dies liegt daran, dass die impliziten Operatormethoden vom Trimmer entfernt werden können, wenn sie nicht im C#-Code verwendet werden. Weitere Informationen zu impliziten Konvertierungsoperatoren finden Sie unter Benutzerdefinierte explizite und implizite Konvertierungsoperatoren.

Betrachten Sie beispielsweise den folgenden Typ, der implizite Konvertierungsoperatoren zwischen SizeRequest und Size:

namespace MyMauiApp;

public struct SizeRequest : IEquatable<SizeRequest>
{
    public Size Request { get; set; }
    public Size Minimum { get; set; }

    public SizeRequest(Size request, Size minimum)
    {
        Request = request;
        Minimum = minimum;
    }

    public SizeRequest(Size request)
    {
        Request = request;
        Minimum = request;
    }

    public override string ToString()
    {
        return string.Format("{{Request={0} Minimum={1}}}", Request, Minimum);
    }

    public bool Equals(SizeRequest other) => Request.Equals(other.Request) && Minimum.Equals(other.Minimum);

    public static implicit operator SizeRequest(Size size) => new SizeRequest(size);
    public static implicit operator Size(SizeRequest size) => size.Request;
    public override bool Equals(object? obj) => obj is SizeRequest other && Equals(other);
    public override int GetHashCode() => Request.GetHashCode() ^ Minimum.GetHashCode();
    public static bool operator ==(SizeRequest left, SizeRequest right) => left.Equals(right);
    public static bool operator !=(SizeRequest left, SizeRequest right) => !(left == right);
}

Wenn die vollständige Kürzung aktiviert ist, können die impliziten Konvertierungsoperatoren zwischen SizeRequest und Size vom Trimmer entfernt werden, wenn sie nicht in Ihrem C#-Code verwendet werden.

Stattdessen sollten Sie einen TypeConverter für Ihren Typ definieren und ihn mit dem Typ anfügen, indem Sie folgendes TypeConverterAttributeverwenden:

using System.ComponentModel;
using System.Diagnostics.CodeAnalysis;
using System.Globalization;

namespace MyMauiApp;

[TypeConverter(typeof(SizeRequestTypeConverter))]
public struct SizeRequest : IEquatable<SizeRequest>
{
    public Size Request { get; set; }
    public Size Minimum { get; set; }

    public SizeRequest(Size request, Size minimum)
    {
        Request = request;
        Minimum = minimum;
    }

    public SizeRequest(Size request)
    {
        Request = request;
        Minimum = request;
    }

    public override string ToString()
    {
        return string.Format("{{Request={0} Minimum={1}}}", Request, Minimum);
    }

    public bool Equals(SizeRequest other) => Request.Equals(other.Request) && Minimum.Equals(other.Minimum);

    public static implicit operator SizeRequest(Size size) => new SizeRequest(size);
    public static implicit operator Size(SizeRequest size) => size.Request;
    public override bool Equals(object? obj) => obj is SizeRequest other && Equals(other);
    public override int GetHashCode() => Request.GetHashCode() ^ Minimum.GetHashCode();
    public static bool operator ==(SizeRequest left, SizeRequest right) => left.Equals(right);
    public static bool operator !=(SizeRequest left, SizeRequest right) => !(left == right);

    private sealed class SizeRequestTypeConverter : TypeConverter
    {
        public override bool CanConvertFrom(ITypeDescriptorContext? context, Type sourceType)
            => sourceType == typeof(Size);

        public override object? ConvertFrom(ITypeDescriptorContext? context, CultureInfo? culture, object value)
            => value switch
            {
                Size size => (SizeRequest)size,
                _ => throw new NotSupportedException()
            };

        public override bool CanConvertTo(ITypeDescriptorContext? context, [NotNullWhen(true)] Type? destinationType)
            => destinationType == typeof(Size);

        public override object? ConvertTo(ITypeDescriptorContext? context, CultureInfo? culture, object? value, Type destinationType)
        {
            if (value is SizeRequest sizeRequest)
            {
                if (destinationType == typeof(Size))
                    return (Size)sizeRequest;
            }
            throw new NotSupportedException();
        }
    }
}

Trimmen von Funktionsschaltern

.NET MAUI verfügt über Trimmerdirektiven, die als Featureoptionen bezeichnet werden, die es ermöglichen, den Code für Features beizubehalten, die nicht sicher sind. Diese Trimmerdirektiven können verwendet werden, wenn die $(TrimMode) Buildeigenschaft auf , sowie für native AOT festgelegt fullist:

Diese MSBuild-Eigenschaften verfügen auch über entsprechende AppContext Schalter:

• Die MauiEnableVisualAssemblyScanning MSBuild-Eigenschaft verfügt über einen entsprechenden AppContext Switch mit dem Namen Microsoft.Maui.RuntimeFeature.IsIVisualAssemblyScanningEnabled.
• Die MauiShellSearchResultsRendererDisplayMemberNameSupported MSBuild-Eigenschaft verfügt über einen entsprechenden AppContext Switch mit dem Namen Microsoft.Maui.RuntimeFeature.IsShellSearchResultsRendererDisplayMemberNameSupported.
• Die MauiQueryPropertyAttributeSupport MSBuild-Eigenschaft verfügt über einen entsprechenden AppContext Switch mit dem Namen Microsoft.Maui.RuntimeFeature.IsQueryPropertyAttributeSupported.
• Die MauiImplicitCastOperatorsUsageViaReflectionSupport MSBuild-Eigenschaft verfügt über einen entsprechenden AppContext Switch mit dem Namen Microsoft.Maui.RuntimeFeature.IsImplicitCastOperatorsUsageViaReflectionSupported.
• Die _MauiBindingInterceptorsSupport MSBuild-Eigenschaft verfügt über einen entsprechenden AppContext Switch mit dem Namen Microsoft.Maui.RuntimeFeature.AreBindingInterceptorsSupported.
• Die MauiEnableXamlCBindingWithSourceCompilation MSBuild-Eigenschaft verfügt über einen entsprechenden AppContext Switch mit dem Namen Microsoft.Maui.RuntimeFeature.MauiEnableXamlCBindingWithSourceCompilationEnabled.
• Die MauiHybridWebViewSupported MSBuild-Eigenschaft verfügt über einen entsprechenden AppContext Switch mit dem Namen Microsoft.Maui.RuntimeFeature.IsHybridWebViewSupported.

Am einfachsten können Sie einen Featureswitch nutzen, indem Sie die entsprechende MSBuild-Eigenschaft in die Projektdatei Ihrer App (*.csproj) einfügen, wodurch der zugehörige Code von den .NET MAUI-Assemblys gekürzt wird.

Code beibehalten

Wenn Sie den Trimmer verwenden, entfernt es manchmal Code, den Sie möglicherweise dynamisch aufgerufen haben, sogar indirekt. Sie können den Trimmer anweisen, Mitglieder beizubehalten, indem Sie sie mit dem DynamicDependency Attribut kommentieren. Dieses Attribut kann verwendet werden, um eine Abhängigkeit entweder von einem Typ und einer Teilmenge von Mitgliedern oder von bestimmten Mitgliedern auszudrücken.

Das Attribut DynamicDependency kann auf Konstruktoren, Felder und Methoden angewendet werden:

[DynamicDependency("Helper", "MyType", "MyAssembly")]
static void RunHelper()
{
    var helper = Assembly.Load("MyAssembly").GetType("MyType").GetMethod("Helper");
    helper.Invoke(null, null);
}

In diesem Beispiel sorgt das DynamicDependency dafür, dass die Methode Helper beibehalten wird. Ohne das Attribut würde Helper die Kürzung vollständig entfernt MyAssembly oder entfernt MyAssembly , wenn sie nicht an anderer Stelle referenziert wird.

Das Attribut gibt das zu behaltende Mitglied über ein string oder über das DynamicallyAccessedMembers-Attribut an. Der Typ und die Assembly sind entweder implizit im Attributkontext oder explizit im Attribut angegeben (durch Type oder durch strings für den Typ und den Assemblynamen).

Die Typ- und Member-Zeichenfolgen verwenden eine Variation des Zeichenfolgenformats der Kommentar-ID aus der C#-Dokumentation ohne das Member-Präfix. Die Memberzeichenfolge sollte nicht den Namen des deklarierenden Typs enthalten und kann Parameter weglassen, um alle Member des angegebenen Namens beizubehalten. Die folgenden Beispiele zeigen gültige Verwendungen:

[DynamicDependency("Method()")]
[DynamicDependency("Method(System,Boolean,System.String)")]
[DynamicDependency("MethodOnDifferentType()", typeof(ContainingType))]
[DynamicDependency("MemberName")]
[DynamicDependency("MemberOnUnreferencedAssembly", "ContainingType", "UnreferencedAssembly")]
[DynamicDependency("MemberName", "Namespace.ContainingType.NestedType", "Assembly")]
// generics
[DynamicDependency("GenericMethodName``1")]
[DynamicDependency("GenericMethod``2(``0,``1)")]
[DynamicDependency("MethodWithGenericParameterTypes(System.Collections.Generic.List{System.String})")]
[DynamicDependency("MethodOnGenericType(`0)", "GenericType`1", "UnreferencedAssembly")]
[DynamicDependency("MethodOnGenericType(`0)", typeof(GenericType<>))]

Beibehalten von Assemblys

Es ist möglich, Assemblys anzugeben, die vom Kürzungsprozess ausgeschlossen werden sollten, während andere Assemblys gekürzt werden können. Dieser Ansatz kann nützlich sein, wenn Sie das DynamicDependency Attribut nicht einfach verwenden können, oder den Code, der gekürzt wird, nicht steuern.

Wenn alle Assemblys gekürzt werden, können Sie den Trimmer anweisen, eine Assembly zu überspringen, indem Sie ein TrimmerRootAssembly MSBuild-Element in der Projektdatei festlegen:

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

Wenn der Trimmer eine Assembly überspringt, wird sie als gewurzelt betrachtet, was bedeutet, dass sie und alle ihre statisch verstandenen Abhängigkeiten beibehalten werden. Sie können zusätzliche Assemblies überspringen, indem Sie weitere TrimmerRootAssembly MSBuild-Eigenschaften zu <ItemGroup> hinzufügen.

Beibehalten von Assemblys, Typen und Elementen

Sie können den Trimmer an eine XML-Beschreibungsdatei übergeben, die angibt, welche Assemblys, Typen und Member aufbewahrt werden müssen.

Um ein Element beim Kürzen aller Assemblys auszuschließen, legen Sie das TrimmerRootDescriptor MSBuild-Element in der Projektdatei auf die XML-Datei fest, die die auszuschließenden Member definiert:

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

Die XML-Datei verwendet dann das Trimmerdeskriptorformat, um zu definieren, welche Member ausgeschlossen werden sollen:

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

In diesem Beispiel gibt die XML-Datei eine Methode an, auf die dynamisch von der App zugegriffen wird, die von der Kürzung ausgeschlossen wird.

Wenn eine Assembly, ein Typ oder ein Element im XML-Code aufgeführt ist, wird die Standardaktion beibehalten. Dies bedeutet, dass der Trimmer unabhängig davon, ob er verwendet wird oder nicht, in der Ausgabe beibehalten wird.

Kennzeichnen einer Assembly als sicher zuschneiden

Wenn Sie über eine Bibliothek in Ihrem Projekt verfügen oder Entwickler einer wiederverwendbaren Bibliothek sind und möchten, dass der Trimmer Die Assembly als trimmbar behandeln kann, können Sie die Assembly als sicher markieren, indem Sie die IsTrimmable MSBuild-Eigenschaft zur Projektdatei für die Assembly hinzufügen:

<PropertyGroup>
    <IsTrimmable>true</IsTrimmable>
</PropertyGroup>

Dadurch wird Ihre Assembly als „kürzbar“ gekennzeichnet, und Kürzungswarnungen werden für dieses Projekt aktiviert. „Kürzbar“ bedeutet, dass Ihre Bibliothek als mit Kürzungen kompatibel gilt und beim Erstellen der Bibliothek keine Kürzungswarnungen enthalten sollte. Wenn die Assembly in einer gekürzten App verwendet wird, werden die nicht verwendeten Member in der finalen Ausgabe gekürzt.

Wenn Sie die native AOT-Bereitstellung in .NET 9+ verwenden, weist das Festlegen der IsAotCompatible MSBuild-Eigenschaft auf true auch der IsTrimmable-Eigenschaft einen Wert von true zu und aktiviert zusätzliche AOT-Analyseeigenschaften für den Build. Weitere Informationen zu AOT-Analyzern finden Sie unter AOT-Kompatibilitätsanalysatoren. Weitere Informationen zur nativen AOT-Bereitstellung für .NET MAUI finden Sie unter Native AOT-Bereitstellung.

Wenn Sie die MSBuild-Eigenschaft IsTrimmable in Ihrer Projektdatei auf true setzen, wird das Attribut AssemblyMetadata in Ihre Assembly eingefügt:

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

Alternativ können Sie das AssemblyMetadata-Attribut in Ihre Assembly einfügen, ohne die IsTrimmable MSBuild-Eigenschaft zur Projektdatei für Ihre Baugruppe hinzugefügt zu haben.

Unterdrücken von Codeanalysewarnungen

Wenn der Trimmer aktiviert ist, entfernt er il, der nicht statisch 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 solche Muster zu warnen, sollten Bibliotheksautoren beim Markieren einer Assembly als sicher zuschneiden die SuppressTrimAnalysisWarnings MSBuild-Eigenschaft auf falseFolgendes festlegen:

<PropertyGroup>
  <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>
</PropertyGroup>

Dies schließt Warnungen zur gesamten App ein, einschließlich Ihres eigenen Codes, Bibliothekscodes und Frameworkcodes.

Anzeigen ausführlicher Warnungen

Die Trimm-Analyse erzeugt höchstens eine Warnung für jede Baugruppe, die von einem PackageReference stammt, was darauf hinweist, dass die Interna der Baugruppe nicht mit dem Trimmen kompatibel sind. Als Bibliotheksautor sollten Sie, wenn Sie eine Assembly als Kürzung sicher markieren, einzelne Warnungen für alle Assemblys aktivieren, indem Sie die TrimmerSingleWarn MSBuild-Eigenschaft auf false:

<PropertyGroup>
  <TrimmerSingleWarn>false</TrimmerSingleWarn>
</PropertyGroup>

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

Siehe auch

• Kürzen eigenständiger Bereitstellungen und ausführbarer Dateien