Konfigurace zatřižovače pro ASP.NET Core Blazor

Tento článek vysvětluje, jak při vytváření aplikace řídit IL trimmer.

Blazor WebAssembly provádí oříznutí zprostředkujícího jazyka (IL), aby se zmenšila velikost publikovaného výstupu. Při publikování aplikace dochází k oříznutí.

Výchozí členitost zatřižovače

Výchozí členitost oříznutí pro Blazor aplikace je partial, což znamená, že se oříznou pouze základní knihovny architektury a knihovny, které mají explicitně povolenou podporu oříznutí. Úplné trimmování není podporováno.

Další informace najdete v tématu Možnosti oříznutí (dokumentace k .NET).

Konfigurace

Chcete-li nakonfigurovat IL Trimmer, přečtěte si článek o možnostech oříznutí v dokumentaci Základy .NET, který obsahuje pokyny k následujícím tématům:

• Zakažte oříznutí pro celou aplikaci s <PublishTrimmed> vlastností v souboru projektu.
• Řídit, jak agresivně nevyužité IL je zahozeno pomocí trimmeru IL.
• Zabraňte IL Trimmeru v trimování konkrétních sestavení.
• Sestavení root pro oříznutí
• Upozornění zařízení Surface pro reflektované typy nastavením <SuppressTrimAnalysisWarnings> vlastnosti do false souboru projektu.
• Podpora oříznutí symbolu ovládacího prvku a ladicí program
• Nastavte funkce il trimmeru pro ořezávání funkcí knihovny architektury.

Pokud je granularita zastřihovače, což je výchozí hodnota, partialIL Trimmer ořízne knihovnu základních tříd a všechny ostatní sestavení označené jako oříznutelné. Pokud chcete aktivovat oříznutí v některém z projektů knihovny tříd aplikace, nastavte <IsTrimmable> vlastnost MSBuild na true v těchto projektech.

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

Pokyny týkající se knihoven .NET najdete v tématu Příprava knihoven .NET na oříznutí.

Selhání zachování typů používaných publikovanou aplikací

Oříznutí může mít negativní vliv na publikovanou aplikaci, která vede k chybám za běhu, i když <PublishTrimmed> vlastnost nastavíte v false souboru projektu. V aplikacích, které používají reflexi, il trimmer často nedokáže určit požadované typy pro odraz modulu runtime a oříznout je pryč nebo oříznout názvy parametrů z metod. K tomu může dojít u složitých typů rozhraní používaných pro JS interoperabilitu, serializaci a deserializaci JSON a další operace.

Il Trimmer také nemůže reagovat na dynamické chování aplikace za běhu. Pokud chcete zajistit, aby oříznutá aplikace po nasazení správně fungovala, otestujte při vývoji často publikovaný výstup.

Podívejte se na následující příklad, který provádí deserializaci JSON do Tuple<T1,T2> kolekce (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)!;
    }
}

Předchozí komponenta se spouští normálně, když je aplikace spuštěna místně a vytvoří následující vykreslený seznam:

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

Když je aplikace publikovaná, Tuple<T1,T2> oříznou se z aplikace, a to i přes nastavení <PublishTrimmed> vlastnosti do false souboru projektu. Přístup ke komponentě vyvolá následující výjimku:

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]

Pokud chcete řešit ztracené typy, zvažte přijetí některého z následujících přístupů.

Vlastní typy

Abyste se vyhnuli problémům s ořezáváním .NET ve scénářích, které spoléhají na reflexi, jako je např. JS interop a serializace JSON, používejte vlastní typy definované v neořezávaných knihovnách nebo zachovejte typy prostřednictvím konfigurace linkeru.

Následující úpravy vytvoří StringTuple typ pro použití komponentou.

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

Komponenta je upravena tak, aby používala StringTuple typ:

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

Vzhledem k tomu, že vlastní typy definované v sestavách, které nelze oříznout, se při publikování aplikace Blazor neoříznou, komponenta funguje podle návrhu i po publikování aplikace.

Pokud dáváte přednost použití typů architektury i přes naše doporučení, použijte některý z následujících přístupů:

• Zachování typu jako dynamické závislosti
• Použití kořenového popisovače

Zachovat typ jako dynamickou závislost

Vytvořte dynamickou závislost, která zachová typ s atributem[DynamicDependency].

Pokud ještě není k dispozici, přidejte direktivu @using pro System.Diagnostics.CodeAnalysis:

@using System.Diagnostics.CodeAnalysis

[DynamicDependency] Přidejte atribut, který zachováTuple<T1,T2>:

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

Použití kořenového popisovače

Kořenový popisovač může zachovat typ.

ILLink.Descriptors.xml Přidejte soubor do kořenového adresáře aplikace† s typem:

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

† Kořenový adresář aplikace odkazuje na kořen Blazor WebAssembly aplikace nebo kořen .Client projektu Blazor Web App (.NET 8 nebo novější).

TrimmerRootDescriptor Přidejte do souboru projektu aplikace položku odkazující na ILLink.Descriptors.xml soubor:

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

{Soubor projektu je buď soubor Blazor WebAssembly projektu aplikace, nebo soubor .Client projektu projektu projektu Blazor Web App (.NET 8 nebo novější).

Další materiály

• Úprava samostatných nasazení a spustitelných souborů
• Příprava knihoven .NET na optimalizaci
• Osvědčené postupy pro zlepšení výkonu díky optimalizaci velikosti stahování aplikací ASP.NET Core Blazor