De trimmer configureren voor ASP.NET Core Blazor

In dit artikel wordt uitgelegd hoe u de Tussenliggende taal (IL) Trimmer kunt beheren bij het bouwen van een Blazor app.

Blazor WebAssembly voert het bijsnijden van tussenliggende taal (IL) uit om de grootte van de gepubliceerde uitvoer te verkleinen. Bij het publiceren van een app treedt bij het bijsnijden van een app op.

Standaard granulariteit van trimmer

De standaardgranulariteit van trimmers voor Blazor apps is partial, wat betekent dat alleen kernframeworkbibliotheken en -bibliotheken waarvoor expliciet ondersteuning voor bijsnijden is ingeschakeld, worden ingekort. Volledig bijsnijden wordt niet ondersteund.

Zie Opties voor bijsnijden (.NET-documentatie) voor meer informatie.

Configuratie

Zie het artikel Met opties voor bijsnijden in de .NET Fundamentals-documentatie, die richtlijnen bevat voor de volgende onderwerpen om de IL Trimmer te configureren:

• Schakel bijsnijden voor de hele app uit met de <PublishTrimmed> eigenschap in het projectbestand.
• Bepaal hoe agressief ongebruikte IL wordt verwijderd door de IL Trimmer.
• Stop de IL Trimmer van het bijsnijden van specifieke assembly's.
• Root-assemblages voor afwerken.
• Surface-waarschuwingen voor weerspiegelde typen door de <SuppressTrimAnalysisWarnings> eigenschap false in te stellen in het projectbestand.
• Ondersteuning voor het trimmeren van controle-symbolen en debugger-ondersteuning.
• IL Trimmer-functies instellen voor het bijsnijden van frameworkbibliotheekfuncties.

Wanneer de granulariteit van de trimmerpartial is, wat de standaardwaarde is, trimt de IL Trimmer de basisclass-bibliotheek en eventuele andere assembly's die als trimbaar zijn gemarkeerd. Als u wilt kiezen voor het bijsnijden van een van de klassebibliotheekprojecten van de app, stelt u de <IsTrimmable> eigenschap true MSBuild in op deze projecten:

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

Zie Bereid .NET-bibliotheken voor op optimalisatie voor richtlijnen met betrekking tot .NET-bibliotheken.

Kan typen die worden gebruikt door een gepubliceerde app niet behouden

Het bijsnijden kan nadelige gevolgen hebben voor een gepubliceerde app die leidt tot runtimefouten, zelfs ondanks het instellen van de <PublishTrimmed> eigenschapfalse in het projectbestand. In apps die reflectie gebruiken, kan de IL Trimmer vaak niet bepalen welke vereiste typen nodig zijn voor runtime-reflectie en worden ze weggeknipt of worden parameternamen van methoden verwijderd. Dit kan gebeuren met complexe frameworktypen die worden gebruikt voor JS interop, JSON-serialisatie/deserialisatie en andere bewerkingen.

De IL Trimmer kan ook tijdens runtime niet reageren op het dynamische gedrag van een app. Test gepubliceerde uitvoer regelmatig tijdens het ontwikkelen om ervoor te zorgen dat de bijgesneden app correct werkt zodra deze is geïmplementeerd.

Bekijk het volgende voorbeeld waarmee JSON-deserialisatie wordt uitgevoerd in een Tuple<T1,T2> verzameling (List<Tuple<string, string>>).

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)!;
    }
}

Het voorgaande onderdeel wordt normaal uitgevoerd wanneer de app lokaal wordt uitgevoerd en produceert de volgende weergegeven lijst:

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

Wanneer de app wordt gepubliceerd, Tuple<T1,T2> wordt deze afgekapt van de app, zelfs ondanks het instellen van de <PublishTrimmed> eigenschap false in het projectbestand. Als u het onderdeel opent, treedt de volgende uitzondering op:

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]

Als u verloren typen wilt aanpakken, kunt u overwegen een van de volgende methoden te gebruiken.

Aangepaste typen

Om problemen met .NET-trimming te voorkomen in scenario's die afhankelijk zijn van reflectie, zoals JS interop en JSON-serilisatie, gebruik aangepaste typen die zijn gedefinieerd in niet-bekortbare bibliotheken, of behoud de typen via linkerconfiguratie.

Met de volgende wijzigingen maakt u een StringTuple type voor gebruik door het onderdeel.

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;
}

Het onderdeel wordt gewijzigd om het StringTuple type te gebruiken:

- 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)!;

Omdat aangepaste typen die zijn gedefinieerd in niet-bijsnijdbare assembly's niet worden ingekort Blazor wanneer een app wordt gepubliceerd, werkt het onderdeel zoals ontworpen nadat de app is gepubliceerd.

Het type behouden als een dynamische afhankelijkheid

Maak een dynamische afhankelijkheid om het type met het [DynamicDependency] kenmerk te behouden.

Als dit nog niet aanwezig is, voegt u een @using richtlijn toe voor System.Diagnostics.CodeAnalysis:

@using System.Diagnostics.CodeAnalysis

Voeg een [DynamicDependency] kenmerk toe om het Tuple<T1,T2>volgende te behouden:

+ [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>

Aanvullende bronnen

• Zelfstandige implementaties en uitvoerbare bestanden knippen
• .NET-bibliotheken voorbereiden voor bijsnijden
• Best practices voor de prestatie van de downloadgrootte van ASP.NET Core-appsBlazor