Konfigurieren des Trimmers für ASP.NET Core Blazor

In diesem Artikel wird erläutert, wie Sie den IL-Trimmer (Intermediate Language, Zwischensprache) beim Erstellen einer Blazor-App steuern.

Blazor WebAssembly führt eine IL-Kürzung (Intermediate Language, Zwischensprache) aus, um die Größe der veröffentlichten Ausgabe zu verringern. Das Abschneiden erfolgt bei der Veröffentlichung einer App.

Standardmäßige Granularität des Trimmers

Die Standardmäßige Trimmer-Granularität für Blazor Apps ist partial, was bedeutet, dass nur Kernframeworkbibliotheken und -bibliotheken, die explizit aktivierte Kürzungsunterstützung haben, gekürzt werden. Die vollständige Kürzung wird nicht unterstützt.

Weitere Informationen finden Sie in der Trimming-Optionen (.NET-Dokumentation).

Konfiguration

Informationen zum Konfigurieren des IL-Trimmers finden Sie im Artikel Kürzungsoptionen in der Dokumentation zu .NET-Grundlagen, die zudem Leitlinien zu folgenden Themen enthält:

• Deaktivieren der Kürzung für die gesamte App mit der Eigenschaft <PublishTrimmed> in der Projektdatei
• Steuern, wie aggressiv nicht verwendete IL vom IL-Trimmer verworfen wird
• Verhindern, dass der IL-Trimmer bestimmte Assemblys kürzt
• „Root“-Assemblys (Stammassemblys) für die Kürzung
• Oberflächenwarnungen für reflektierte Typen, indem die <SuppressTrimAnalysisWarnings>-Eigenschaft in der Projektdatei auf false festgelegt wird.
• Steuern der Symbolkürzung und Debuggerunterstützung
• Festlegen von IL-Trimmerfeatures für Bibliotheksfeatures des Trimmingframeworks

Wenn es sich bei der Trimmer-Granularitätpartialum den Standardwert handelt, schneidet der IL Trimmer die Basisklassenbibliothek und alle anderen Assemblys, die als trimmbar gekennzeichnet sind. Um das Kürzen in einem der Klassenbibliotheksprojekte der App zu aktivieren, legen Sie die <IsTrimmable> MSBuild-Eigenschaft true in diesen Projekten fest:

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

Anleitungen zu .NET-Bibliotheken finden Sie unter Vorbereiten von .NET-Bibliotheken zum Kürzen.

Fehler beim Beibehalten von Typen, die von einer veröffentlichten App verwendet werden

Das Kürzen kann nachteilige Auswirkungen für eine veröffentlichte App haben, die zu Laufzeitfehlern führt, auch wenn die <PublishTrimmed> Eigenschaft in der Projektdatei festgelegt false wird. In Apps, die Spiegelung verwenden, kann der IL Trimmer häufig nicht die erforderlichen Typen für die Laufzeitspiegelung bestimmen und sie abschneiden oder Parameternamen von Methoden abschneiden. Dies kann bei komplexen Frameworktypen geschehen, die für JS Interop, JSON-Serialisierung/Deserialisierung und andere Vorgänge verwendet werden.

Der IL-Trimmer kann auch nicht auf das dynamische Verhalten einer App zur Laufzeit reagieren. Wenn Sie sicherstellen möchten, dass die gekürzte App nach der Bereitstellung ordnungsgemäß funktioniert, testen Sie während der Entwicklung regelmäßig die veröffentlichte Ausgabe.

Betrachten Sie das folgende Beispiel, das JSON-Deserialisierung in einer Tuple<T1,T2> Auflistung (List<Tuple<string, string>>) durchführt.

TrimExample.razor:

@page "/trim-example"
@using System.Diagnostics.CodeAnalysis
@using System.Text.Json

<h1>Trim Example</h1>

<ul>
    @foreach (var item in @items)
    {
        <li>@item.Item1, @item.Item2</li>
    }
</ul>

@code {
    private List<Tuple<string, string>> items = [];

    [StringSyntax(StringSyntaxAttribute.Json)]
    private const string data =
        """[{"item1":"1:T1","item2":"1:T2"},{"item1":"2:T1","item2":"2:T2"}]""";

    protected override void OnInitialized()
    {
        JsonSerializerOptions options = new() { PropertyNameCaseInsensitive = true };

        items = JsonSerializer
            .Deserialize<List<Tuple<string, string>>>(data, options)!;
    }
}

Die vorhergehende Komponente wird normalerweise ausgeführt, wenn die App lokal ausgeführt wird und die folgende gerenderte Liste erzeugt:

• 1:T1, 1:T2
• 2:T2, 2:T2

Wenn die App veröffentlicht wird, Tuple<T1,T2> wird sie von der App gekürzt, auch wenn die <PublishTrimmed> Eigenschaft in der Projektdatei festgelegt false wird. Der Zugriff auf die Komponente löst die folgende Ausnahme aus:

crit: Microsoft.AspNetCore.Components.WebAssembly.Rendering.WebAssemblyRenderer[100]
Unhandled exception rendering component: ConstructorContainsNullParameterNames, System.Tuple`2[System.String,System.String]
System.NotSupportedException: ConstructorContainsNullParameterNames, System.Tuple`2[System.String,System.String]

Um verlorene Typen zu beheben, sollten Sie eine der folgenden Ansätze anwenden.

Benutzerdefinierte Typen

Verwenden Sie benutzerdefinierte Typen, die in nicht trimmbaren Bibliotheken definiert sind, oder bewahren Sie die Typen über die Linkerkonfiguration auf, um Probleme mit .NET-Kürzungen in Szenarien zu vermeiden, die auf Spiegelung basieren, z JS . B. interop- und JSON-Serialisierung.

Die folgenden Änderungen erstellen einen StringTuple Typ für die Verwendung durch die Komponente.

StringTuple.cs:

[method: SetsRequiredMembers]
public sealed class StringTuple(string item1, string item2)
{
    public required string Item1 { get; init; } = item1;
    public required string Item2 { get; init; } = item2;
}

Die Komponente wird geändert, um den StringTuple Typ zu verwenden:

- private List<Tuple<string, string>> items = [];
+ private List<StringTuple> items = [];

- items = JsonSerializer.Deserialize<List<Tuple<string, string>>>(data, options)!;
+ items = JsonSerializer.Deserialize<List<StringTuple>>(data, options)!;

Da benutzerdefinierte Typen, die in nicht trimmbaren Assemblys definiert sind, beim Veröffentlichen einer App nicht gekürzt werden, funktioniert die Komponente wie vorgesehen nach der Veröffentlichung der App.

Erhalte den Typ als dynamische Abhängigkeit

Erstellen Sie eine dynamische Abhängigkeit, um den Typ mit dem [DynamicDependency] Attribut beizubehalten.

Falls noch nicht vorhanden, fügen Sie eine @using Direktive für System.Diagnostics.CodeAnalysis:

@using System.Diagnostics.CodeAnalysis

Fügen Sie ein [DynamicDependency] Attribut hinzu, um folgendes Tuple<T1,T2>beizubehalten:

+ [DynamicDependency(DynamicallyAccessedMemberTypes.PublicConstructors, 
+     typeof(Tuple<string, string>))]
private List<Tuple<string, string>> items = [];

<linker>
  <assembly fullname="System.Private.CoreLib">
    <type fullname="System.Tuple`2" preserve="all" />
  </assembly>
</linker>

<ItemGroup>
  <TrimmerRootDescriptor Include="$(MSBuildThisFileDirectory)ILLink.Descriptors.xml" />
</ItemGroup>

<PropertyGroup>
  <_ExtraTrimmerArgs>--keep-metadata parametername</_ExtraTrimmerArgs>
</PropertyGroup>

Zusätzliche Ressourcen

• Kürzen eigenständiger Bereitstellungen und ausführbarer Dateien
• Vorbereiten von .NET-Bibliotheken für das Trimmen
• Bewährte Methoden zur Verbesserung der Download-Größe von ASP.NET Core-Apps Blazor