Opožděné načtení sestavení v ASP.NET Core Blazor WebAssembly

Blazor WebAssembly Výkon spouštění aplikace je možné zlepšit čekáním na načtení sestavení aplikací vytvořených vývojářem, dokud se sestavení nevyžadují, což se nazývá opožděné načítání.

Počáteční části tohoto článku se týkají konfigurace aplikace. Funkční ukázku najdete v části Kompletní příklad na konci tohoto článku.

Tento článek se týká jenom Blazor WebAssembly aplikací. Opožděné načítání sestavení nepřináší výhody pro serverové aplikace, protože aplikace vykreslené na straně serveru nestahují sestavení do klienta.

Opožděné načítání by se nemělo používat pro sestavení pro hlavní běhové prostředí, která mohou být při publikování oříznuta a při načítání aplikace nedostupná na klientovi.

Zástupný symbol přípony souboru ({FILE EXTENSION}) pro soubory sestavení

Soubory sestavení používají formát balení Webcil pro sestavení .NET s příponou .wasm souboru.

V celém článku {FILE EXTENSION} představuje zástupný symbol "wasm".

Konfigurace souboru projektu

Označte sestavení k opožděnému načítání v souboru projektu aplikace (.csproj) pomocí položky BlazorWebAssemblyLazyLoad. Použijte název sestavení s příponou souboru. Architektura Blazor brání sestavení při spuštění aplikace.

<ItemGroup>
  <BlazorWebAssemblyLazyLoad Include="{ASSEMBLY NAME}.{FILE EXTENSION}" />
</ItemGroup>

Zástupný {ASSEMBLY NAME} symbol je název sestavení a {FILE EXTENSION} zástupný symbol je přípona souboru. Přípona souboru je povinná.

Zahrňte jednu BlazorWebAssemblyLazyLoad položku pro každé sestavení. Pokud sestavení obsahuje závislosti, zahrňte BlazorWebAssemblyLazyLoad položku pro každou závislost.

Router konfigurace komponent

Architektura Blazor automaticky zaregistruje jednu službu pro opožděné načítání sestavení v aplikacích na straně Blazor WebAssembly klienta . LazyAssemblyLoader Metoda LazyAssemblyLoader.LoadAssembliesAsync:

• Používá JS interoperabilitu k načtení sestavení prostřednictvím síťového volání.
• Načte sestavení do běhového prostředí, které běží na WebAssembly v prohlížeči.

Blazor Router Komponenta určuje sestavení, která Blazor vyhledá směrovatelné komponenty, a je také zodpovědná za vykreslení komponenty pro trasu, ve které uživatel prochází. Metoda Router komponenty OnNavigateAsync se používá ve spojení s opožděným načítáním k načtení správných sestavení pro koncové body, které uživatel požaduje.

Logika je implementována v rámci OnNavigateAsync pro určení sestavení, která se mají načíst pomocí LazyAssemblyLoader. Mezi možnosti strukturování logiky patří:

• Podmíněné kontroly uvnitř OnNavigateAsync metody.
• Vyhledávací tabulka, která mapuje trasy na jména sestavení, která jsou buď vložena do komponenty, nebo jsou implementována v kódu komponenty.

V následujícím příkladu:

• Obor názvů pro Microsoft.AspNetCore.Components.WebAssembly.Services je specifikován.
• Služba LazyAssemblyLoader je vložena (AssemblyLoader).
• Zástupný {PATH} symbol označuje cestu, kde by se měl načíst seznam sestavení. Příklad používá podmíněnou kontrolu jedné cesty, která načte jednu sadu sestavení.
• Zástupný symbol {LIST OF ASSEMBLIES} je seznam názvů souborů sestavení, oddělený čárkami, včetně jejich přípon (například "Assembly1.{FILE EXTENSION}", "Assembly2.{FILE EXTENSION}").

App.razor:

@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.WebAssembly.Services
@using Microsoft.Extensions.Logging
@inject LazyAssemblyLoader AssemblyLoader
@inject ILogger<App> Logger

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext args)
    {
        try
           {
               if (args.Path == "{PATH}")
               {
                   var assemblies = await AssemblyLoader.LoadAssembliesAsync(
                       [ {LIST OF ASSEMBLIES} ]);
               }
           }
           catch (Exception ex)
           {
               Logger.LogError("Error: {Message}", ex.Message);
           }
    }
}

Poznámka:

Předchozí příklad nezobrazuje obsah markupu komponenty RouterRazor (...). Ukázku s úplným kódem najdete v části Kompletní příklad tohoto článku.

Sestavení, která obsahují směrovatelné komponenty

Pokud seznam sestavení obsahuje směrovatelné komponenty, je seznam sestavení pro danou cestu předán kolekci komponenty RouterAdditionalAssemblies.

V následujícím příkladu:

• Seznam v < předává seznam sestavení do Assembly. Architektura vyhledá trasy a aktualizuje kolekci tras, pokud jsou nalezeny nové trasy. Pro přístup k typu Assembly je obor názvů System.Reflection uvedený v horní části souboru App.razor.
• Zástupný {PATH} symbol označuje cestu, kde by se měl načíst seznam sestavení. Příklad používá podmíněnou kontrolu jedné cesty, která načte jednu sadu sestavení.
• Zástupný symbol {LIST OF ASSEMBLIES} je seznam názvů souborů sestavení, oddělený čárkami, včetně jejich přípon (například "Assembly1.{FILE EXTENSION}", "Assembly2.{FILE EXTENSION}").

App.razor:

@using System.Reflection
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.WebAssembly.Services
@using Microsoft.Extensions.Logging
@inject ILogger<App> Logger
@inject LazyAssemblyLoader AssemblyLoader

<Router AppAssembly="typeof(App).Assembly" 
    AdditionalAssemblies="lazyLoadedAssemblies" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private List<Assembly> lazyLoadedAssemblies = [];

    private async Task OnNavigateAsync(NavigationContext args)
    {
        try
        {
            if (args.Path == "{PATH}")
            {
                var assemblies = await AssemblyLoader.LoadAssembliesAsync(
                    [ {LIST OF ASSEMBLIES} ]);
                lazyLoadedAssemblies.AddRange(assemblies);
            }
        }
        catch (Exception ex)
        {
            Logger.LogError("Error: {Message}", ex.Message);
        }
    }
}

Poznámka:

Předchozí příklad nezobrazuje obsah markupu komponenty RouterRazor (...). Ukázku s úplným kódem najdete v části Kompletní příklad tohoto článku.

Další informace najdete v tématu ASP.NET Blazor Základní směrování a navigace.

Interakce uživatelů s obsahem <Navigating>

Při načítání sestavení, které může trvat několik sekund, může komponenta Router označit uživateli, že s vlastností Navigating směrovače probíhá přechod stránky.

Další informace najdete v tématu ASP.NET Blazor Základní směrování a navigace.

Řešení zrušení v OnNavigateAsync

Objekt NavigationContext předaný do zpětného volání OnNavigateAsync obsahuje CancellationToken, která se nastaví při nové události navigace. OnNavigateAsync Zpětné volání musí vyvolat, když je token zrušení nastavený, aby se zabránilo pokračování ve spouštění zpětného OnNavigateAsync volání v zastaralé navigaci.

Další informace najdete v tématu ASP.NET Blazor Základní směrování a navigace.

Kompletní příklad

Ukázka v této části:

• Vytvoří sestavu ovládání robota (GrantImaharaRobotControls.{FILE EXTENSION}) jako knihovnu tříd Razor (RCL), která zahrnuje komponentu Robot (Robot.razor s šablonou trasy /robot).
• Lenivě načte sestavení RCL, aby vykreslilo jeho Robot komponentu, když uživatel požaduje /robot adresu URL.

Vytvořte samostatnou Blazor WebAssembly aplikaci, která demonstruje opožděné načítání Razor sestavení knihovny tříd. Pojmenujte projekt LazyLoadTest.

Do řešení přidejte projekt knihovny tříd ASP.NET Core:

• Visual Studio: Klikněte pravým tlačítkem na soubor řešení v Průzkumník řešení a vyberte >. V dialogovém okně nových typů projektů vyberte Razor knihovnu tříd. Pojmenujte projekt GrantImaharaRobotControls. nezaškrtávejte políčko Stránky podpory a zobrazení.
• Visual Studio Code/.NET CLI: Spusťte dotnet new razorclasslib -o GrantImaharaRobotControls z příkazového řádku. Tato -o|--output možnost vytvoří složku a pojmenuje projekt GrantImaharaRobotControls.

Vytvořte HandGesture třídu v RCL s metodou ThumbUp, která hypoteticky přiměje robota provést gesto 'palec nahoru'. Metoda přijímá argument pro osu, Left nebo Right, jako enum. Metoda vrátí true, pokud je úspěšná.

HandGesture.cs:

using Microsoft.Extensions.Logging;

namespace GrantImaharaRobotControls;

public static class HandGesture
{
    public static bool ThumbUp(Axis axis, ILogger logger)
    {
        logger.LogInformation("Thumb up gesture. Axis: {Axis}", axis);

        // Code to make robot perform gesture

        return true;
    }
}

public enum Axis { Left, Right }

Do kořenového adresáře projektu RCL přidejte následující komponentu. Tato komponenta uživateli umožňuje odeslat žádost o gesto pro palec doleva nebo doprava.

Robot.razor:

@page "/robot"
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.Extensions.Logging
@inject ILogger<Robot> Logger

<h1>Robot</h1>

<EditForm FormName="RobotForm" Model="robotModel" OnValidSubmit="HandleValidSubmit">
    <InputRadioGroup @bind-Value="robotModel.AxisSelection">
        @foreach (var entry in Enum.GetValues<Axis>())
        {
            <InputRadio Value="entry" />
            <text>&nbsp;</text>@entry<br>
        }
    </InputRadioGroup>

    <button type="submit">Submit</button>
</EditForm>

<p>
    @message
</p>

@code {
    private RobotModel robotModel = new() { AxisSelection = Axis.Left };
    private string? message;

    private void HandleValidSubmit()
    {
        Logger.LogInformation("HandleValidSubmit called");

        var result = HandGesture.ThumbUp(robotModel.AxisSelection, Logger);

        message = $"ThumbUp returned {result} at {DateTime.Now}.";
    }

    public class RobotModel
    {
        public Axis AxisSelection { get; set; }
    }
}

V projektu LazyLoadTest vytvořte referenci na projekt GrantImaharaRobotControls RCL:

• Visual Studio: Klikněte pravým tlačítkem myši na LazyLoadTest projekt a vyberte Přidat>odkaz na projekt, abyste přidali odkaz na projekt pro GrantImaharaRobotControls RCL.
• Visual Studio Code/.NET CLI: Spusťte dotnet add reference {PATH} v příkazovém prostředí ze složky projektu. Zástupný {PATH} symbol je cesta k projektu RCL.

Zadejte sestavení RCL pro opožděné načítání v projektovém souboru aplikace LazyLoadTest (.csproj):

<ItemGroup>
    <BlazorWebAssemblyLazyLoad Include="GrantImaharaRobotControls.{FILE EXTENSION}" />
</ItemGroup>

Následující Router komponenta demonstruje načítání GrantImaharaRobotControls.{FILE EXTENSION} sestavení, když uživatel přechází na /robot. Nahraďte výchozí App komponentu aplikace následující App komponentou.

Během přechodů stránky se uživateli zobrazí stylovaná zpráva s prvkem <Navigating> . Další informace najdete v části Interakce uživatele s <Navigating> obsahem.

Sestavení je přiřazeno AdditionalAssemblies, což má za následek, že směrovač hledá v sestavení směrovatelné komponenty, kde najde prvek Robot. Trasa Robot komponenty se přidá do kolekce tras aplikace. Další informace najdete v článku o směrování a navigaci v ASP.NET Core Blazor a v části tohoto článku sestavení, která obsahují směrovatelné součásti.

App.razor:

@using System.Reflection
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.WebAssembly.Services
@using Microsoft.Extensions.Logging
@inject ILogger<App> Logger
@inject LazyAssemblyLoader AssemblyLoader

<Router AppAssembly="typeof(App).Assembly"
        AdditionalAssemblies="lazyLoadedAssemblies" 
        OnNavigateAsync="OnNavigateAsync">
    <Navigating>
        <div style="padding:20px;background-color:blue;color:white">
            <p>Loading the requested page&hellip;</p>
        </div>
    </Navigating>
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(MainLayout)" />
    </Found>
    <NotFound>
        <LayoutView Layout="typeof(MainLayout)">
            <p>Sorry, there's nothing at this address.</p>
        </LayoutView>
    </NotFound>
</Router>

@code {
    private List<Assembly> lazyLoadedAssemblies = [];
    private bool grantImaharaRobotControlsAssemblyLoaded;

    private async Task OnNavigateAsync(NavigationContext args)
    {
        try
        {
            if ((args.Path == "robot") && !grantImaharaRobotControlsAssemblyLoaded)
            {
                var assemblies = await AssemblyLoader.LoadAssembliesAsync(
                    [ "GrantImaharaRobotControls.{FILE EXTENSION}" ]);
                lazyLoadedAssemblies.AddRange(assemblies);
                grantImaharaRobotControlsAssemblyLoaded = true;
            }
        }
        catch (Exception ex)
        {
            Logger.LogError("Error: {Message}", ex.Message);
        }
    }
}

Zkompilujte a spusťte aplikaci.

Když je komponenta Robot z RCL požadována na /robot, načte se knihovna GrantImaharaRobotControls.{FILE EXTENSION} a vykreslí se komponenta Robot. Načítání sestavení můžete prozkoumat na kartě Síť v nástrojích prohlížeče pro vývojáře.

Odstraňování potíží

• Pokud dojde k neočekávanému vykreslování, například vykreslení komponenty z předchozí navigace, ověřte, že kód vyvolá, pokud je nastaven token zrušení.
• Pokud se sestavení nakonfigurovaná pro opožděné načítání neočekávaně načítá při spuštění aplikace, zkontrolujte, jestli je sestavení označené pro opožděné načítání v souboru projektu.

Další materiály

• Zpracování asynchronních navigačních událostí pomocí OnNavigateAsync
• Osvědčené postupy pro výkon ASP.NET Core Blazor