Menghosting aplikasi web Blazor di aplikasi .NET MAUI menggunakan BlazorWebView

Artikel
10/02/2024

UI Aplikasi Multi-platform .NET (.NET MAUI) BlazorWebView adalah kontrol yang memungkinkan Anda menghosting aplikasi web Blazor di aplikasi MAUI .NET Anda. Aplikasi ini, yang dikenal sebagai aplikasi Blazor Hybrid, memungkinkan aplikasi web Blazor untuk diintegrasikan dengan fitur platform dan kontrol UI. Kontrol BlazorWebView dapat ditambahkan ke halaman mana pun dari aplikasi .NET MAUI, dan diakhir ke akar aplikasi Blazor. Komponen Razor berjalan secara asli dalam proses .NET dan merender UI web ke kontrol tampilan web yang disematkan. Di .NET MAUI, aplikasi Blazor Hybrid dapat berjalan di semua platform yang didukung oleh .NET MAUI.

BlazorWebView menentukan properti berikut:

HostPage, dari jenis string?, yang mendefinisikan halaman akar aplikasi web Blazor.
RootComponents, dari jenis RootComponentsCollection, yang menentukan kumpulan komponen akar yang dapat ditambahkan ke kontrol.
StartPath, dari jenis string, yang menentukan jalur untuk navigasi awal dalam konteks navigasi Blazor ketika komponen Blazor selesai dimuat.

Kelas RootComponent menentukan properti berikut:

Selector, dari jenis string?, yang menentukan string pemilih CSS yang menentukan di mana dalam dokumen komponen harus ditempatkan.
ComponentType, dari jenis Type?, yang mendefinisikan jenis komponen akar.
Parameters, dari jenis IDictionary<string, object?>?, yang mewakili kamus opsional parameter untuk diteruskan ke komponen akar.

Selain itu, BlazorWebView menentukan peristiwa berikut:

BlazorWebViewInitializing, dengan objek yang menyertainya BlazorWebViewInitializingEventArgs , yang dinaikkan sebelum diinisialisasi BlazorWebView . Kejadian ini memungkinkan penyesuaian BlazorWebView konfigurasi.
BlazorWebViewInitialized, dengan objek yang menyertainya BlazorWebViewInitializedEventArgs , yang dinaikkan setelah diinisialisasi BlazorWebView tetapi sebelum komponen apa pun dirender. Kejadian ini memungkinkan pengambilan instans tampilan web khusus platform.
UrlLoading, dengan objek yang menyertainya UrlLoadingEventArgs , dinaikkan saat hyperlink diklik dalam BlazorWebView. Kejadian ini memungkinkan kustomisasi apakah hyperlink dibuka di BlazorWebView, di aplikasi eksternal, atau apakah upaya pemuatan URL dibatalkan.

Komponen Razor yang ada dapat digunakan dalam aplikasi Blazor .NET MAUI dengan memindahkan kode ke dalam aplikasi, atau dengan mereferensikan pustaka kelas atau paket yang ada yang berisi komponen. Untuk informasi selengkapnya, lihat Menggunakan kembali komponen Razor di ASP.NET Core Blazor Hybrid.

Alat pengembang browser dapat digunakan untuk memeriksa aplikasi Blazor .NET MAUI. Untuk informasi selengkapnya, lihat Menggunakan alat pengembang browser dengan ASP.NET Core Blazor Hybrid.

Catatan

Meskipun Visual Studio menginstal semua alat yang diperlukan untuk mengembangkan aplikasi Blazor .NET MAUI, pengguna akhir aplikasi Blazor .NET MAUI di Windows harus menginstal runtime WebView2 .

Untuk informasi selengkapnya tentang aplikasi Blazor Hybrid, lihat ASP.NET Core Blazor Hybrid.

Membuat aplikasi Blazor .NET MAUI

Aplikasi Blazor .NET MAUI dapat dibuat di Visual Studio oleh templat aplikasi .NET MAUI Blazor:

Cuplikan layar templat proyek aplikasi .NET MAUI Blazor.

Templat proyek ini membuat aplikasi Blazor .NET MAUI multitarget yang dapat disebarkan ke Android, iOS, macOS, dan Windows. Untuk instruksi langkah demi langkah tentang membuat aplikasi Blazor .NET MAUI, lihat Membuat aplikasi Blazor .NET MAUI.

Yang BlazorWebView dibuat oleh templat proyek didefinisikan dalam MainPage.xaml, dan menunjuk ke akar aplikasi 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>

Komponen Razor akar untuk aplikasi berada di Main.razor, yang dikompilasi Razor menjadi jenis bernama Main di namespace layanan akar aplikasi. Komponen Razor lainnya berada di folder Halaman dan Proyek bersama, dan identik dengan komponen yang digunakan dalam templat web Blazor default. Aset web statis untuk aplikasi berada di folder wwwroot .

Menambahkan BlazorWebView ke aplikasi yang sudah ada

Proses untuk menambahkan BlazorWebView ke aplikasi .NET MAUI yang ada adalah sebagai berikut:

Tambahkan Razor SDK, Microsoft.NET.Sdk.Razor ke proyek Anda dengan mengedit baris pertama file proyek CSPROJ:
```
<Project Sdk="Microsoft.NET.Sdk.Razor">
```
Razor SDK diperlukan untuk membangun dan mengemas proyek yang berisi file Razor untuk proyek Blazor.
Tambahkan komponen Razor root untuk aplikasi ke proyek.
Tambahkan komponen Razor Anda ke folder proyek bernama Pages dan Shared.
Tambahkan aset web statis Anda ke folder proyek bernama wwwroot.
Tambahkan file _Imports.razor opsional ke proyek Anda.

BlazorWebView Tambahkan ke halaman di aplikasi .NET MAUI Anda, dan arahkan ke akar aplikasi 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>

CreateMauiApp Ubah metode kelas Anda MauiProgram untuk mendaftarkan BlazorWebView kontrol untuk digunakan di aplikasi Anda. Untuk melakukan ini, pada IServiceCollection objek , panggil AddMauiBlazorWebView metode untuk menambahkan layanan tampilan web komponen ke kumpulan layanan:

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

Mengakses layanan terlingkup dari UI asli

BlazorWebView memiliki TryDispatchAsync metode yang dapat memanggil secara asinkron tertentu Action<ServiceProvider> dan meneruskan layanan terlingkup yang tersedia dalam komponen Razor. Ini memungkinkan kode dari UI asli untuk mengakses layanan terlingkup seperti 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.
    }
}

Mendiagnosis masalah

BlazorWebView memiliki pengelogan bawaan yang dapat membantu Anda mendiagnosis masalah di aplikasi Blazor Hybrid Anda. Ada dua langkah untuk mengaktifkan pengelogan ini:

Aktifkan BlazorWebView dan komponen terkait untuk mencatat informasi diagnostik.
Konfigurasikan pencatat untuk menulis output log ke tempat Anda dapat melihatnya.

Untuk informasi selengkapnya tentang pengelogan, lihat Pengelogan di C# dan .NET.

Mengaktifkan pengelogan BlazorWebView

Semua konfigurasi pengelogan dapat dilakukan sebagai bagian dari pendaftaran layanan dalam sistem injeksi dependensi. Untuk mengaktifkan pengelogan maksimum untuk BlazorWebView komponen terkait dan di bawah Microsoft.AspNetCore.Components.WebView namespace layanan, tambahkan kode berikut ke tempat layanan aplikasi Anda didaftarkan:

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

Atau, untuk mengaktifkan pengelogan maksimum untuk setiap komponen yang menggunakan Microsoft.Extensions.Logging, Anda dapat menggunakan kode berikut:

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

Mengonfigurasi output pengelogan dan melihat output

Setelah mengonfigurasi komponen untuk menulis informasi log, Anda perlu mengonfigurasi ke mana pencatat harus menulis log, lalu melihat output log.

Penyedia pengelogan Debug menulis output menggunakan Debug pernyataan, dan output dapat dilihat dari Visual Studio.

Untuk mengonfigurasi penyedia pengelogan Debug , pertama-tama tambahkan referensi di proyek Anda ke Microsoft.Extensions.Logging.Debug paket NuGet. Kemudian, daftarkan penyedia di dalam panggilan ke AddLogging yang Anda tambahkan di langkah sebelumnya dengan memanggil AddDebug metode ekstensi:

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

Saat menjalankan aplikasi dari Visual Studio (dengan debugging diaktifkan), Anda dapat melihat output debug di jendela Output Visual Studio.

Memutar video sebaris di iOS

Untuk memutar video sebaris di aplikasi hibrid Blazor di iOS, dalam BlazorWebView, Anda harus:

Atur properti UrlLoadingStrategy ke OpenInWebView. Ini dapat dicapai di penanganan aktivitas untuk peristiwa:UrlLoading

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

Pastikan bahwa AllowsInlineMediaPlayback properti dalam Configuration objek diatur ke true. Ini dapat dicapai di penanganan aktivitas untuk peristiwa:BlazorWebViewInitializing
```
private void BlazorWebViewInitializing(object? sender, BlazorWebViewInitializingEventArgs e)
{
#if IOS
    e.Configuration.AllowsInlineMediaPlayback = true;
#endif
}
```

Memperbaiki kebuntuan pembuangan di Android

Secara default, BlazorWebView melakukan pembuangan asinkron-over-sync, yang berarti memblokir utas hingga pembuangan asinkron selesai. Namun, ini dapat menyebabkan kebuntuan jika pembuangan perlu menjalankan kode pada utas yang sama (karena utas diblokir saat menunggu).

Jika Anda mengalami hang di Android dengan BlazorWebView Anda harus mengaktifkan AppContext sakelar dalam CreateMauiApp metode di MauiProgram.cs:

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

Sakelar ini memungkinkan BlazorWebView untuk menembak dan melupakan pembuangan asinkron yang terjadi, dan sebagai hasilnya memperbaiki sebagian besar kebuntuan pembuangan yang terjadi di Android.

Peringatan

Mengaktifkan sakelar ini berarti bahwa pembuangan dapat kembali sebelum semua objek dibuang, yang dapat menyebabkan perubahan perilaku di aplikasi Anda. Item yang dibuang sebagian adalah jenis internal Blazor sendiri, tetapi juga jenis yang ditentukan aplikasi seperti layanan tercakup yang digunakan dalam BlazorWebView bagian aplikasi Anda.

Menghosting konten menggunakan perilaku warisan di iOS dan Mac Catalyst

Di iOS dan Mac Catalyst 18, perilaku default untuk menghosting konten dalam telah berubah menjadi BlazorWebView localhost. Alamat internal 0.0.0.1 yang digunakan untuk menghosting konten tidak lagi berfungsi dan menghasilkan BlazorWebView tidak memuat konten apa pun dan penyajian sebagai persegi panjang kosong.

Untuk memilih menggunakan 0.0.0.1 alamat, tambahkan kode berikut ke CreateMauiApp metode di MauiProgram.cs:

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

Bagikan melalui