Ładowanie zestawów z opóźnieniem w ASP.NET Core Blazor WebAssembly

Blazor WebAssembly Wydajność uruchamiania aplikacji można poprawić, czekając na załadowanie zestawów aplikacji utworzonych przez deweloperów, dopóki zestawy nie będą wymagane, co jest nazywane ładowaniem leniwym.

W pierwszych sekcjach tego artykułu omówiono konfigurację aplikacji. Aby zapoznać się z pokazem roboczym, zobacz sekcję Kompletny przykład na końcu tego artykułu.

Ten artykuł dotyczy Blazor WebAssembly tylko aplikacji. Ładowanie zestawów z opóźnieniem nie przynosi korzyści aplikacjom po stronie serwera, ponieważ aplikacje renderowane na serwerze nie pobierają zestawów do klienta.

Ładowanie opóźnione nie powinno być używane w przypadku podstawowych zestawów środowiska uruchomieniowego, które mogą być przycinane podczas publikowania i niedostępności na kliencie podczas ładowania aplikacji.

Symbol zastępczy rozszerzenia pliku ({FILE EXTENSION}) dla plików zestawów

Pliki zestawów używają formatu pakietu Webcil dla zestawów .NET z .wasm rozszerzeniem pliku.

W całym artykule {FILE EXTENSION} symbol zastępczy reprezentuje znak "wasm".

Konfiguracja pliku projektu

Oznacz zestawy do ładowania z opóźnieniem w pliku projektu aplikacji (.csproj) przy użyciu BlazorWebAssemblyLazyLoad elementu . Użyj nazwy zestawu z rozszerzeniem pliku. Platforma Blazor uniemożliwia ładowanie zestawu podczas uruchamiania aplikacji.

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

Symbol {ASSEMBLY NAME} zastępczy to nazwa zestawu, a {FILE EXTENSION} symbol zastępczy to rozszerzenie pliku. Rozszerzenie pliku jest wymagane.

Uwzględnij jeden BlazorWebAssemblyLazyLoad element dla każdego zestawu. Jeśli zestaw ma zależności, dołącz BlazorWebAssemblyLazyLoad wpis dla każdej zależności.

Router konfiguracja składnika

Platforma Blazor automatycznie rejestruje pojedynczą usługę do ładowania zestawów z opóźnieniem w aplikacjach po stronie Blazor WebAssembly klienta, LazyAssemblyLoader. Metoda LazyAssemblyLoader.LoadAssembliesAsync:

• Używa JS międzyoperacyjności do pobierania zestawów za pośrednictwem wywołania sieciowego.
• Ładuje zestawy do środowiska uruchomieniowego wykonywanego w zestawie WebAssembly w przeglądarce.

BlazorRouter Składnik "s wyznacza zestawy, które Blazor wyszukują składniki routingu, a także jest odpowiedzialny za renderowanie składnika dla trasy, w której nawiguje użytkownik. Router Metoda składnika OnNavigateAsync jest używana w połączeniu z ładowaniem leniwym w celu załadowania poprawnych zestawów dla punktów końcowych żądanych przez użytkownika.

Logika jest implementowana wewnątrz OnNavigateAsync , aby określić zestawy do załadowania za pomocą LazyAssemblyLoaderpolecenia . Opcje struktury logiki obejmują:

• Testy warunkowe wewnątrz OnNavigateAsync metody .
• Tabela odnośników, która mapuje trasy na nazwy zestawów, wprowadzone do składnika lub zaimplementowane w @code bloku.

W poniższym przykładzie:

• Określona jest przestrzeń nazw Microsoft.AspNetCore.Components.WebAssembly.Services .
• Usługa LazyAssemblyLoader jest wstrzykiwana (AssemblyLoader).
• Symbol {PATH} zastępczy to ścieżka, w której powinna zostać załadowana lista zestawów. W przykładzie użyto sprawdzania warunkowego dla pojedynczej ścieżki, która ładuje pojedynczy zestaw zestawów.
• Symbol {LIST OF ASSEMBLIES} zastępczy to rozdzielona przecinkami lista ciągów nazw plików zestawu, w tym ich rozszerzeń plików (na przykład "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(
                       new[] { {LIST OF ASSEMBLIES} });
               }
           }
           catch (Exception ex)
           {
               Logger.LogError("Error: {Message}", ex.Message);
           }
    }
}

Uwaga

W poprzednim przykładzie nie jest wyświetlana zawartość Router znaczników składnika Razor (...). Aby zapoznać się z pokazem z pełnym kodem, zobacz sekcję Kompletny przykład tego artykułu.

Zestawy zawierające składniki routingu

Gdy lista zestawów zawiera składniki routingu, lista zestawów dla danej ścieżki jest przekazywana AdditionalAssemblies do Router kolekcji składnika.

W poniższym przykładzie:

• Lista Assembly<>na liście lazyLoadedAssemblies przekazuje listę zestawów do .AdditionalAssemblies Platforma wyszukuje zestawy tras i aktualizuje kolekcję tras, jeśli zostaną znalezione nowe trasy. Aby uzyskać dostęp do Assembly typu, przestrzeń nazw dla System.Reflection elementu znajduje się w górnej App.razor części pliku.
• Symbol {PATH} zastępczy to ścieżka, w której powinna zostać załadowana lista zestawów. W przykładzie użyto sprawdzania warunkowego dla pojedynczej ścieżki, która ładuje pojedynczy zestaw zestawów.
• Symbol {LIST OF ASSEMBLIES} zastępczy to rozdzielona przecinkami lista ciągów nazw plików zestawu, w tym ich rozszerzeń plików (na przykład "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 = new();

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

Uwaga

W poprzednim przykładzie nie jest wyświetlana zawartość Router znaczników składnika Razor (...). Aby zapoznać się z pokazem z pełnym kodem, zobacz sekcję Kompletny przykład tego artykułu.

Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor routing i nawigacja.

Interakcja użytkownika z zawartością <Navigating>

Podczas ładowania zestawów, co może potrwać kilka sekund, składnik może wskazać użytkownikowi, Router że przejście strony odbywa się z właściwością routera Navigating .

Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor routing i nawigacja.

Obsługa anulowania w programie OnNavigateAsync

NavigationContext Obiekt przekazany do wywołania zwrotnego OnNavigateAsync zawiera element CancellationToken ustawiony, gdy wystąpi nowe zdarzenie nawigacji. Wywołanie OnNavigateAsync zwrotne musi zostać zgłoszony, gdy token anulowania jest ustawiony, aby uniknąć dalszego uruchamiania OnNavigateAsync wywołania zwrotnego w nieaktualnej nawigacji.

Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor routing i nawigacja.

OnNavigateAsync zdarzenia i pliki zestawów o zmienionej nazwie

Moduł ładujący zasobów opiera się na nazwach zestawów zdefiniowanych blazor.boot.json w pliku. Jeśli nazwy zestawów zostaną zmienione, nazwy zestawów używane w wywołaniu zwrotnym OnNavigateAsync i nazwy zestawów w blazor.boot.json pliku nie są zsynchronizowane.

Aby rozwiązać ten problem:

• Sprawdź, czy aplikacja jest uruchomiona w Production środowisku podczas określania nazw zestawów do użycia.
• Zapisz nazwy zestawów o zmienionej nazwie w osobnym pliku i odczytaj z tego pliku, aby określić nazwę zestawu, która ma być używana z usługą LazyAssemblyLoader i OnNavigateAsync wywołaniem zwrotnym.

Kompletny przykład

Pokaz w tej sekcji:

• Tworzy zestaw kontrolek robota (GrantImaharaRobotControls.{FILE EXTENSION}) jako bibliotekę Razor klas (RCL), która zawiera Robot składnik (Robot.razor z szablonem /robottrasy ).
• Lazily ładuje zestaw listy RCL w celu renderowania jego Robot składnika, gdy /robot adres URL jest żądany przez użytkownika.

Utwórz autonomiczną Blazor WebAssembly aplikację, aby zademonstrować leniwe ładowanie Razor zestawu biblioteki klas. Nadaj projektowi LazyLoadTestnazwę .

Dodaj projekt biblioteki klas ASP.NET Core do rozwiązania:

• Visual Studio: kliknij prawym przyciskiem myszy plik rozwiązania w Eksplorator rozwiązań i wybierz polecenie Dodaj>nowy projekt. W oknie dialogowym nowych typów projektów wybierz pozycję Razor Biblioteka klas. Nadaj projektowi GrantImaharaRobotControlsnazwę . Nie zaznaczaj pól wyboru Strony pomocy technicznej i wyświetl.
• Visual Studio Code/.NET CLI: wykonaj dotnet new razorclasslib -o GrantImaharaRobotControls polecenie w wierszu polecenia. Opcja -o|--output tworzy folder i nada projektowi GrantImaharaRobotControlsnazwę .

Przykładowy składnik przedstawiony w dalszej części tej sekcji używa Blazor formularza. W projekcie listy RCL dodaj Microsoft.AspNetCore.Components.Forms pakiet do projektu.

Uwaga

Aby uzyskać instrukcje dodawania pakietów do aplikacji .NET, zobacz artykuły w sekcji Instalowanie pakietów i zarządzanie nimi w temacie Przepływ pracy użycia pakietów (dokumentacja programu NuGet). Sprawdź prawidłowe wersje pakietów pod adresem NuGet.org.

Utwórz klasę HandGesture na liście RCL za pomocą ThumbUp metody, która hipotetycznie sprawia, że robot wykonuje gest kciuka w górę. Metoda akceptuje argument osi Left lub Right, jako enum. Metoda zwraca true powodzenie.

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 }

Dodaj następujący składnik do katalogu głównego projektu listy RCL. Składnik umożliwia użytkownikowi przesłanie żądania gestu z lewej lub prawej strony.

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

W projekcie LazyLoadTest utwórz odwołanie do projektu dla listy GrantImaharaRobotControls RCL:

• Visual Studio: kliknij projekt prawym przyciskiem myszy LazyLoadTest i wybierz polecenie Dodaj>odwołanie do projektu, aby dodać odwołanie do projektu dla GrantImaharaRobotControls listy RCL.
• Visual Studio Code/.NET CLI: wykonaj dotnet add reference {PATH} polecenie w powłoce poleceń z folderu projektu. Symbol {PATH} zastępczy to ścieżka do projektu listy RCL.

Określ zestaw listy RCL na potrzeby ładowania z opóźnieniem LazyLoadTest w pliku projektu aplikacji (.csproj):

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

Poniższy Router składnik demonstruje ładowanie GrantImaharaRobotControls.{FILE EXTENSION} zestawu, gdy użytkownik przejdzie do /robotelementu . Zastąp domyślny App składnik aplikacji następującym App składnikiem.

Podczas przechodzenia strony wyświetlany jest użytkownikowi stylizowany komunikat z elementem <Navigating> . Aby uzyskać więcej informacji, zobacz sekcję Interakcja użytkownika z zawartością<Navigating>.

Zestaw jest przypisywany do AdditionalAssemblieselementu , co powoduje przeszukiwanie zestawu pod kątem składników routingu Robot , gdzie znajduje składnik. Trasa Robot składnika jest dodawana do kolekcji tras aplikacji. Aby uzyskać więcej informacji, zobacz artykuł ASP.NET Core Blazor routingu i nawigacji oraz sekcję Zestawy zawierające składniki routingu w tym artykule.

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 = new();

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

Skompiluj i uruchom aplikację.

Robot Gdy składnik z listy RCL jest żądany na /robotstronie , GrantImaharaRobotControls.{FILE EXTENSION} zestaw jest ładowany, a Robot składnik jest renderowany. Ładowanie zestawu można sprawdzić na karcie Sieć w narzędziach deweloperskich przeglądarki.

Rozwiązywanie problemów

• Jeśli wystąpi nieoczekiwane renderowanie, takie jak renderowanie składnika z poprzedniej nawigacji, upewnij się, że kod zgłasza błąd, jeśli token anulowania został ustawiony.
• Jeśli zestawy skonfigurowane do nieoczekiwanego ładowania leniwego podczas uruchamiania aplikacji, sprawdź, czy zestaw jest oznaczony do leniwego ładowania w pliku projektu.

Dodatkowe zasoby

• Obsługa zdarzeń nawigacji asynchronicznej za pomocą polecenia OnNavigateAsync
• najlepsze rozwiązania dotyczące wydajności ASP.NET Core Blazor