Hostování webové aplikace Blazor v aplikaci .NET MAUI pomocí BlazorWebView

Článek
11/14/2024

Uživatelské rozhraní aplikace .NET s více platformami (.NET MAUI) BlazorWebView je ovládací prvek, který umožňuje hostovat webovou aplikaci Blazor ve vaší aplikaci .NET MAUI. Tyto aplikace, označované jako Hybridní aplikace Blazor, umožňují integraci webové aplikace Blazor s funkcemi platformy a ovládacími prvky uživatelského rozhraní. Ovládací BlazorWebView prvek lze přidat na libovolnou stránku aplikace .NET MAUI a odkazovat na kořen aplikace Blazor. Komponenty Razor běží nativně v procesu .NET a vykreslují webové uživatelské rozhraní do vloženého ovládacího prvku webového zobrazení. V .NET MAUI můžou hybridní aplikace Blazor běžet na všech platformách podporovaných rozhraním .NET MAUI.

BlazorWebView definuje následující vlastnosti:

HostPage, typu string?, který definuje kořenovou stránku webové aplikace Blazor.
RootComponents, typu RootComponentsCollection, který určuje kolekci kořenových komponent, které lze přidat do ovládacího prvku.
StartPath, typu string, který definuje cestu pro počáteční navigaci v rámci navigačního kontextu Blazor při dokončení načítání komponenty Blazor.

Třída RootComponent definuje následující vlastnosti:

Selector, typu string?, který definuje řetězec selektoru CSS, který určuje, kde v dokumentu má být komponenta umístěna.
ComponentType, typu Type?, který definuje typ kořenové komponenty.
Parameters, typu IDictionary<string, object?>?, který představuje volitelný slovník parametrů pro předání kořenové součásti.

Kromě toho BlazorWebView definuje následující události:

BlazorWebViewInitializing, s doprovodným BlazorWebViewInitializingEventArgs objektem, který je vyvolán před BlazorWebView inicializován. Tato událost umožňuje přizpůsobení BlazorWebView konfigurace.
BlazorWebViewInitialized, s doprovodným BlazorWebViewInitializedEventArgs objektem, který je vyvolán po BlazorWebView inicializaci, ale před vykreslení jakékoli součásti. Tato událost umožňuje načtení instance webového zobrazení specifické pro platformu.
UrlLoading, s doprovodným UrlLoadingEventArgs objektem je vyvolán při kliknutí hypertextového odkazu v rámci BlazorWebView. Tato událost umožňuje přizpůsobit, zda je hypertextový odkaz otevřen v BlazorWebViewexterní aplikaci, nebo zda je zrušen pokus o načtení adresy URL.

Existující komponenty Razor je možné použít v aplikaci .NET MAUI Blazor přesunutím kódu do aplikace nebo odkazováním na existující knihovnu tříd nebo balíček, který tuto komponentu obsahuje. Další informace najdete v tématu Opětovné použití komponent Razor v ASP.NET Core Blazor Hybrid.

Nástroje pro vývojáře prohlížeče je možné použít ke kontrole aplikací .NET MAUI Blazor. Další informace najdete v tématu Použití vývojářských nástrojů prohlížeče s ASP.NET Core Blazor Hybrid.

Poznámka:

Zatímco Visual Studio nainstaluje všechny požadované nástroje pro vývoj aplikací .NET MAUI Blazor, koncoví uživatelé aplikací .NET MAUI Blazor ve Windows musí nainstalovat modul runtime WebView2 .

Další informace o hybridních aplikacích Blazor najdete v tématu ASP.NET Core Blazor Hybrid.

Vytvoření aplikace .NET MAUI Blazor

Aplikaci .NET MAUI Blazor můžete vytvořit v sadě Visual Studio pomocí šablony aplikace .NET MAUI Blazor:

Snímek obrazovky šablony projektu aplikace .NET MAUI Blazor

Tato šablona projektu vytvoří více cílenou aplikaci .NET MAUI Blazor, která se dá nasadit do Androidu, iOS, macOS a Windows. Podrobné pokyny k vytvoření aplikace .NET MAUI Blazor najdete v tématu Vytvoření aplikace .NET MAUI Blazor.

Šablona BlazorWebView projektu je definována v souboru MainPage.xaml a odkazuje na kořen aplikace Blazor:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:BlazorWebViewDemo"
             x:Class="BlazorWebViewDemo.MainPage"
             BackgroundColor="{DynamicResource PageBackgroundColor}">

    <BlazorWebView HostPage="wwwroot/index.html">
        <BlazorWebView.RootComponents>
            <RootComponent Selector="#app" ComponentType="{x:Type local:Main}" />
        </BlazorWebView.RootComponents>
    </BlazorWebView>

</ContentPage>

Kořenová komponenta Razor pro aplikaci je v Main.razor, kterou Razor zkompiluje do typu pojmenovaného Main v kořenovém oboru názvů aplikace. Zbývající komponenty Razor jsou ve složkách pages a sdílených projektů a jsou identické s komponentami použitými ve výchozí webové šabloně Blazor. Statické webové prostředky aplikace jsou ve složce wwwroot .

Přidání Objektu BlazorWebView do existující aplikace

Postup přidání BlazorWebView do existující aplikace .NET MAUI je následující:

Přidejte do projektu sadu Razor SDK Microsoft.NET.Sdk.Razor úpravou prvního řádku souboru projektu CSPROJ:
```
<Project Sdk="Microsoft.NET.Sdk.Razor">
```
Sada Razor SDK se vyžaduje k sestavení a zabalení projektů obsahujících soubory Razor pro projekty Blazor.
Přidejte do projektu kořenovou komponentu Razor pro aplikaci.
Přidejte komponenty Razor do složek projektu s názvem Pages a Shared.
Přidejte statické webové prostředky do složky projektu s názvem wwwroot.
Přidejte do projektu všechny volitelné soubory _Imports.razor .

BlazorWebView Přidejte do své aplikace .NET MAUI stránku a nasměrujte ji na kořen aplikace Blazor:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:MyBlazorApp"
             x:Class="MyBlazorApp.MainPage">

    <BlazorWebView HostPage="wwwroot/index.html">
        <BlazorWebView.RootComponents>
            <RootComponent Selector="#app" ComponentType="{x:Type local:Main}" />
        </BlazorWebView.RootComponents>
    </BlazorWebView>

</ContentPage>

Upravte metodu CreateMauiApp třídy MauiProgram , aby se ovládací prvek zaregistroval BlazorWebView pro použití v aplikaci. Uděláte to tak, že v objektu IServiceCollection zavoláte metodu AddMauiBlazorWebView pro přidání služeb webového zobrazení komponent do kolekce služeb:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        builder.Services.AddMauiBlazorWebView();
#if DEBUG
        builder.Services.AddBlazorWebViewDeveloperTools();
#endif
        // Register any app services on the IServiceCollection object
        // e.g. builder.Services.AddSingleton<WeatherForecastService>();

        return builder.Build();
    }
}

Tento kód také umožňuje vývojářské nástroje na podkladových ovládacích prvcích WebView, když je aplikace spuštěná v konfiguraci ladění.

Přístup ke službám s vymezeným oborem z nativního uživatelského rozhraní

BlazorWebView má metodu TryDispatchAsync , která může volat zadanou Action<ServiceProvider> asynchronně a předávat vymezené služby dostupné v komponentách Razor. To umožňuje kódu z nativního uživatelského rozhraní přistupovat ke službám s vymezeným oborem, například NavigationManager:

private async void OnMyMauiButtonClicked(object sender, EventArgs e)
{
    var wasDispatchCalled = await blazorWebView.TryDispatchAsync(sp =>
    {
        var navMan = sp.GetRequiredService<NavigationManager>();
        navMan.CallSomeNavigationApi(...);
    });

    if (!wasDispatchCalled)
    {
        // Consider what to do if it the dispatch fails - that's up to your app to decide.
    }
}

Diagnostika problémů

BlazorWebView obsahuje integrované protokolování, které vám může pomoct s diagnostikou problémů v hybridní aplikaci Blazor. Toto protokolování můžete povolit dvěma kroky:

Povolte BlazorWebView a související komponenty pro protokolování diagnostických informací.
Nakonfigurujte protokolovací nástroj pro zápis výstupu protokolu do místa, kde ho můžete zobrazit.

Další informace o protokolování najdete v tématu Protokolování v jazyce C# a .NET.

Povolení protokolování BlazorWebView

Veškerou konfiguraci protokolování je možné provést jako součást registrace služby v systému injektáže závislostí. Pokud chcete povolit maximální protokolování pro BlazorWebView a související komponenty v Microsoft.AspNetCore.Components.WebView oboru názvů, přidejte do místa, kde jsou zaregistrované služby vaší aplikace:

services.AddLogging(logging =>
{
    logging.AddFilter("Microsoft.AspNetCore.Components.WebView", LogLevel.Trace);
});

Případně můžete povolit maximální protokolování pro každou komponentu, která používá Microsoft.Extensions.Logging, použít následující kód:

services.AddLogging(logging =>
{
    logging.SetMinimumLevel(LogLevel.Trace);
});

Konfigurace výstupu protokolování a zobrazení výstupu

Po konfiguraci komponent pro zápis informací protokolu je potřeba nakonfigurovat, kam protokolovací nástroje mají protokoly zapisovat, a pak zobrazit výstup protokolu.

Zprostředkovatelé protokolování ladění zapisují výstup pomocí Debug příkazů a výstup lze zobrazit ze sady Visual Studio.

Pokud chcete nakonfigurovat zprostředkovatele protokolování ladění , nejprve do balíčku NuGet přidejte do projektu Microsoft.Extensions.Logging.Debug odkaz. Potom zaregistrujte poskytovatele uvnitř volání AddLogging , které jste přidali v předchozím kroku voláním AddDebug metody rozšíření:

services.AddLogging(logging =>
{
    logging.AddFilter("Microsoft.AspNetCore.Components.WebView", LogLevel.Trace);
    logging.AddDebug();
});

Když spustíte aplikaci ze sady Visual Studio (s povoleným laděním), můžete zobrazit výstup ladění v okně Výstup sady Visual Studio.

Přehrávání vloženého videa v iOSu

Pokud chcete přehrát vložené video v hybridní aplikaci Blazor v iOSu BlazorWebView, měli byste:

Nastavte vlastnost UrlLoadingStrategy na OpenInWebView. To lze provést v obslužné rutině události pro UrlLoading událost:

private void BlazorUrlLoading(object? sender, UrlLoadingEventArgs e)
{
#if IOS
    e.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView;
#endif
}

Ujistěte se, že AllowsInlineMediaPlayback vlastnost v objektu Configuration je nastavena na true. To lze provést v obslužné rutině události pro BlazorWebViewInitializing událost:
```
private void BlazorWebViewInitializing(object? sender, BlazorWebViewInitializingEventArgs e)
{
#if IOS
    e.Configuration.AllowsInlineMediaPlayback = true;
#endif
}
```

Vyřazení zablokování v Androidu

Ve výchozím nastavení BlazorWebView se aktivuje a zapomene asynchronní odstranění podkladu WebViewManager. Tím se snižuje potenciál zablokování pro odstranění v Androidu.

Upozorňující

Toto výchozí chování typu fire-and-forget znamená, že odstranění může vrátit před odstraněním všech objektů, což může způsobit změny chování ve vaší aplikaci. Uvolněné položky jsou částečně vlastními interními typy Blazoru, ale také typy definované aplikací, jako jsou služby s vymezeným oborem používané v BlazorWebView rámci části vaší aplikace.

Pokud se chcete z tohoto chování odhlásit, měli byste nakonfigurovat aplikaci tak, aby blokovala odstranění prostřednictvím AppContext přepínače v CreateMauiApp metodě ve vaší MauiProgram třídě:

AppContext.SetSwitch("BlazorWebView.AndroidFireAndForgetAsync", false);

Pokud je vaše aplikace nakonfigurovaná tak, aby blokovala odstranění prostřednictvím tohoto přepínače, BlazorWebView provede async-over-sync dispose, což znamená, že blokuje vlákno, dokud se asynchronní odstranění neskončí. To však může způsobit zablokování, pokud je potřeba k odstranění spustit kód ve stejném vlákně (protože vlákno je blokováno při čekání).

Hostování obsahu pomocí staršího způsobu chování

Výchozí chování pro hostování obsahu v BlazorWebView se změnilo na 0.0.0.1. Interní 0.0.0.0 adresa použitá k hostování obsahu už nefunguje a výsledkem BlazorWebView není načtení žádného obsahu a vykreslení jako prázdný obdélník.

Pokud se chcete přihlásit k používání 0.0.0.0 adresy, přidejte do metody v CreateMauiAppMauiProgram.cs následující kód:

// Set this switch to use the LEGACY behavior of always using 0.0.0.0 to host BlazorWebView
AppContext.SetSwitch("BlazorWebView.AppHostAddressAlways0000", true);

Sdílet prostřednictvím