Размещение веб-приложения Blazor в приложении .NET MAUI с помощью BlazorWebView

Статья
11/14/2024

Многоплатформенный пользовательский интерфейс приложения .NET (.NET MAUI) BlazorWebView — это элемент управления, позволяющий размещать веб-приложение Blazor в приложении .NET MAUI. Эти приложения, известные как гибридные приложения Blazor, позволяют интегрировать веб-приложение Blazor с функциями платформы и элементами управления пользовательским интерфейсом. Элемент BlazorWebView управления можно добавить на любую страницу приложения .NET MAUI и указать корень приложения Blazor. Компоненты Razor выполняются изначально в процессе .NET и отображают веб-интерфейс в внедренном элементе управления веб-представления. В .NET MAUI гибридные приложения Blazor могут работать на всех платформах, поддерживаемых .NET MAUI.

BlazorWebView определяет следующие свойства:

HostPageтипа string?, который определяет корневую страницу веб-приложения Blazor.
RootComponents RootComponentsCollectionТип , который указывает коллекцию корневых компонентов, которые можно добавить в элемент управления.
StartPathТип string, который определяет путь для начальной навигации в контексте навигации Blazor после завершения загрузки компонента Blazor.

Класс RootComponent определяет следующие свойства:

Selectorтипа string?, который определяет строку селектора CSS, указывающую, где в документе должен размещаться компонент.
ComponentTypeтипа Type?, который определяет тип корневого компонента.
Parametersтип IDictionary<string, object?>?, представляющий необязательный словарь параметров для передачи корневому компоненту.

Кроме того, BlazorWebView определяет следующие события:

BlazorWebViewInitializingс сопутствующим BlazorWebViewInitializingEventArgs объектом, который вызывается перед BlazorWebView инициализацией. Это событие включает настройку BlazorWebView конфигурации.
BlazorWebViewInitializedс сопутствующим BlazorWebViewInitializedEventArgs объектом, который возникает после BlazorWebView инициализации, но до отрисовки любого компонента. Это событие позволяет получить экземпляр веб-представления для конкретной платформы.
UrlLoadingПри щелчке гиперссылки в пределах объекта UrlLoadingEventArgsвозникает сопроводительный BlazorWebView объект. Это событие позволяет настроить, открывается ли гиперссылка в BlazorWebViewвнешнем приложении или отменяется ли попытка загрузки URL-адреса.

Существующие компоненты Razor можно использовать в приложении .NET MAUI Blazor, переместив код в приложение или ссылаясь на существующую библиотеку классов или пакет, содержащий компонент. Дополнительные сведения см. в разделе "Повторное использование компонентов Razor" в ASP.NET Core Blazor Hybrid.

Средства разработчика браузера можно использовать для проверки приложений .NET MAUI Blazor. Дополнительные сведения см. в разделе "Использование средств разработчика браузера" с ASP.NET Core Blazor Hybrid.

Примечание.

Хотя Visual Studio устанавливает все необходимые средства для разработки приложений .NET MAUI Blazor, конечные пользователи приложений .NET MAUI Blazor в Windows должны установить среду выполнения WebView2 .

Дополнительные сведения о гибридных приложениях Blazor см. в разделе ASP.NET Core Blazor Hybrid.

Создание приложения .NET MAUI Blazor

Приложение .NET MAUI Blazor можно создать в Visual Studio с помощью шаблона приложения .NET MAUI Blazor:

Снимок экрана шаблона проекта приложения .NET MAUI Blazor.

Этот шаблон проекта создает многоцелевой приложение .NET MAUI Blazor, которое можно развернуть в Android, iOS, macOS и Windows. Пошаговые инструкции по созданию приложения .NET MAUI Blazor см. в статье о создании приложения .NET MAUI Blazor.

Созданный BlazorWebView шаблоном проекта определен в MainPage.xaml и указывает на корень приложения 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>

Корневой компонент Razor для приложения находится в Main.razor, который Razor компилируется в тип с именем Main в корневом пространстве имен приложения. Остальные компоненты Razor находятся в папках страниц и общих проектов и идентичны компонентам, используемым в веб-шаблоне Blazor по умолчанию. Статические веб-ресурсы для приложения находятся в папке wwwroot .

Добавление BlazorWebView в существующее приложение

Процесс добавления BlazorWebView в существующее приложение MAUI .NET выглядит следующим образом:

Добавьте пакет SDK Razor в проект, Microsoft.NET.Sdk.Razor изменив первую строку файла проекта CSPROJ:
```
<Project Sdk="Microsoft.NET.Sdk.Razor">
```
Пакет SDK Razor необходим для сборки и упаковки проектов, содержащих файлы Razor для проектов Blazor.
Добавьте корневой компонент Razor для приложения в проект.
Добавьте компоненты Razor в папки проекта с именем Pages и Shared.
Добавьте статические веб-ресурсы в папку проекта с именем wwwroot.
Добавьте в проект любые необязательные файлы _Imports.razor .

BlazorWebView Добавьте страницу в приложение .NET MAUI и укажите его корень приложения 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 метод MauiProgram класса, чтобы зарегистрировать BlazorWebView элемент управления для использования в приложении. Для этого вызовите IServiceCollectionAddMauiBlazorWebView метод для добавления служб веб-представления компонентов в коллекцию служб:
```
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();
    }
}
```
Этот код также включает средства разработчика в базовых элементах управления WebView, когда приложение выполняется в конфигурации отладки.

Доступ к службам с областью действия из собственного пользовательского интерфейса

BlazorWebView имеет метод, который может вызывать указанный TryDispatchAsyncAction<ServiceProvider> асинхронно и передавать в области служб, доступных в компонентах Razor. Это позволяет коду из собственного пользовательского интерфейса получать доступ к службам с областью действия, таким как 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.
    }
}

Диагностические проблемы

BlazorWebView имеет встроенное ведение журнала, которое помогает диагностировать проблемы в гибридном приложении Blazor. Для включения этого ведения журнала необходимо выполнить два шага.

Включите BlazorWebView и связанные компоненты для журналов диагностических сведений.
Настройте средство ведения журнала для записи выходных данных журнала в том месте, где его можно просмотреть.

Дополнительные сведения о ведении журнала см. в разделе "Ведение журнала" в C# и .NET.

Включение ведения журнала BlazorWebView

Всю конфигурацию ведения журнала можно выполнить как часть регистрации службы в системе внедрения зависимостей. Чтобы включить максимальное ведение журнала для BlazorWebView и связанных компонентов в Microsoft.AspNetCore.Components.WebView пространстве имен, добавьте следующий код в место регистрации служб приложения:

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

Кроме того, чтобы включить максимальное ведение журнала для каждого используемого Microsoft.Extensions.Loggingкомпонента, можно использовать следующий код:

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

Настройка выходных данных журнала и просмотр выходных данных

После настройки компонентов для записи сведений журнала необходимо настроить, где средства ведения журнала должны записывать журналы, а затем просматривать выходные данные журнала.

Поставщики ведения журнала отладки записывают выходные данные с помощью Debug инструкций, а выходные данные можно просмотреть из Visual Studio.

Чтобы настроить поставщика ведения журнала отладки , сначала добавьте ссылку в проект Microsoft.Extensions.Logging.Debug в пакет NuGet. Затем зарегистрируйте поставщика внутри вызова AddLogging , который вы добавили на предыдущем шаге, вызвав AddDebug метод расширения:

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

При запуске приложения из Visual Studio (с включенной отладкой) можно просмотреть выходные данные отладки в окне вывода Visual Studio.

Воспроизведение встроенного видео в iOS

Чтобы воспроизвести встроенное видео в гибридном приложении Blazor в iOS, введите BlazorWebViewследующее:

Установите свойство UrlLoadingStrategy в значение OpenInWebView. Это можно сделать в обработчике событий для UrlLoading события:
```
private void BlazorUrlLoading(object? sender, UrlLoadingEventArgs e)
{
#if IOS
    e.UrlLoadingStrategy = UrlLoadingStrategy.OpenInWebView;
#endif
}
```
Убедитесь, что AllowsInlineMediaPlayback для свойства объекта Configuration задано trueзначение . Это можно сделать в обработчике событий для BlazorWebViewInitializing события:
```
private void BlazorWebViewInitializing(object? sender, BlazorWebViewInitializingEventArgs e)
{
#if IOS
    e.Configuration.AllowsInlineMediaPlayback = true;
#endif
}
```

Взаимоблокировки удаления в Android

По умолчанию BlazorWebView активирует и забывает асинхронное удаление базового WebViewManager. Это снижает вероятность возникновения взаимоблокировок удаления в Android.

Предупреждение

Это поведение по умолчанию означает, что удаление может вернуться до удаления всех объектов, что может привести к изменению поведения в приложении. Элементы, которые удаляются, частично являются собственными внутренними типами Blazor, но и определяемыми приложением типами, такими как службы с областью действия, используемые в BlazorWebView пределах части приложения.

Чтобы отказаться от этого поведения, необходимо настроить приложение для блокировки удаления с помощью коммутатора AppContext в методе CreateMauiApp в классе MauiProgram :

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

Если приложение настроено на блокировку удаления с помощью этого коммутатора, BlazorWebView выполняет асинхронное удаление синхронизации, то есть блокирует поток до завершения асинхронного удаления. Однако это может привести к взаимоблокировкам, если удаление должно выполнять код в одном потоке (так как поток заблокирован во время ожидания).

Размещайте контент с использованием устаревшего режима

Стандартное поведение для размещения содержимого в BlazorWebView изменилось на 0.0.0.1. Внутренний 0.0.0.0 адрес, используемый для размещения содержимого, больше не работает и приводит к тому, BlazorWebView что не загружается содержимое и отрисовка в виде пустого прямоугольника.

Чтобы воспользоваться адресом 0.0.0.0 , добавьте следующий код в CreateMauiApp метод в MauiProgram.cs:

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

Поделиться через