Hospedar um aplicativo Web Blazor em um aplicativo .NET MAUI usando o BlazorWebView

Artigo
05/14/2024

O Interface de usuário do Aplicativo Multiplataforma do .NET (.NET MAUI) BlazorWebView é um controle que permite hospedar um aplicativo Web do Blazor em seu aplicativo .NET MAUI. Esses aplicativos, conhecidos como aplicativos Híbridos Blazor, permitem que um aplicativo Web Blazor seja integrado com recursos da plataforma e controles de interface do usuário. O controle BlazorWebView pode ser adicionado a qualquer página de um aplicativo .NET MAUI e apontado para a raiz do aplicativo Blazor. Os componentes Razor são executados nativamente no processo .NET e renderizam a interface do usuário da Web em um controle de exibição da Web inserido. No .NET MAUI, os aplicativos Blazor Hybrid podem ser executados em todas as plataformas com suporte pelo .NET MAUI.

BlazorWebView define as propriedades a seguir:

HostPage, do tipo string?, que define a página raiz do aplicativo Web Blazor.
RootComponents, do tipo RootComponentsCollection, que especifica a coleção de componentes raiz que podem ser adicionados ao controle.
StartPath, do tipo string, que define o caminho para a navegação inicial no contexto de navegação do Blazor quando o componente Blazor termina de ser carregado.

A classe RootComponent define as seguintes propriedades:

Selector, do tipo string?, que define a cadeia de caracteres de seletores CSS que especifica onde o componente deve ser colocado no documento.
ComponentType, do tipo Type?, que define o tipo do componente raiz.
Parameters, do tipo IDictionary<string, object?>?, que representa um dicionário opcional de parâmetros a serem passados para o componente raiz.

Além disso, BlazorWebView define os seguintes eventos:

BlazorWebViewInitializing, com um objeto BlazorWebViewInitializingEventArgs que o acompanha, que é gerado antes da inicialização do BlazorWebView. Esse evento permite a personalização da configuração do BlazorWebView.
BlazorWebViewInitialized, com um objeto BlazorWebViewInitializedEventArgs associado, que é gerado após a inicialização do BlazorWebView, mas antes que qualquer componente tenha sido renderizado. Esse evento permite a recuperação da instância de visualização da Web específica da plataforma.
UrlLoading, com um objeto UrlLoadingEventArgs que o acompanha, é acionado quando um hiperlink é clicado em um BlazorWebView. Esse evento permite personalizar se um hiperlink é aberto no BlazorWebView, em um aplicativo externo ou se a tentativa de carregamento da URL foi cancelada.

Os componentes do Razor existentes podem ser usados em um aplicativo .NET MAUI Blazor movendo o código para o aplicativo ou fazendo referência a uma biblioteca de classes ou pacote existente que contenha o componente. Para obter mais informações, consulte Reutilizar componentes Razor no ASP.NET Core Blazor Hybrid.

As ferramentas de desenvolvedor do navegador podem ser usadas para inspecionar aplicativos .NET MAUI Blazor. Para obter mais informações, consulte Usar ferramentas de desenvolvedor de navegador com o ASP.NET Core Blazor Hybrid.

Observação

Enquanto o Visual Studio instala todas as ferramentas necessárias para desenvolver aplicativos .NET MAUI Blazor, os usuários finais de aplicativos .NET MAUI Blazor no Windows devem instalar o runtime WebView2.

Para obter mais informações sobre os aplicativos Blazor Hybrid, consulte ASP.NET Core Blazor Hybrid.

Criar um aplicativo .NET MAUI Blazor

Um aplicativo .NET MAUI Blazor pode ser criado no Visual Studio pelo modelo de aplicativo .NET MAUI Blazor:

Captura de tela do modelo de projeto de aplicativo .NET MAUI Blazor.

Esse modelo de projeto cria um aplicativo .NET MAUI Blazor com vários destinos que pode ser implantado no Android, iOS, macOS e Windows. Para obter instruções passo a passo sobre como criar um aplicativo .NET MAUI Blazor, consulte Criar um aplicativo .NET MAUI Blazor.

O BlazorWebView criado pelo modelo de projeto é definido em MainPage.xaml e aponta para a raiz do aplicativo 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>

O componente do Razor raiz do aplicativo está em Main.razor, que o Razor compila em um tipo chamado Main no namespace raiz do aplicativo. O restante dos componentes Razor está nas pastas do projeto Pages e Shared e é idêntico aos componentes usados no modelo padrão da Web do Blazor. Os ativos estáticos da Web para o aplicativo estão na pasta wwwroot.

Adicionar um BlazorWebView a um aplicativo existente

O processo para adicionar um BlazorWebView a um aplicativo .NET MAUI existente é o seguinte:

Adicione o SDK do Razor, Microsoft.NET.Sdk.Razor ao seu projeto editando a primeira linha do arquivo de projeto CSPROJ:
```
<Project Sdk="Microsoft.NET.Sdk.Razor">
```
O SDK do Razor é necessário para criar e empacotar projetos que contenham arquivos Razor para projetos do Blazor.
Adicione o componente do Razor raiz do aplicativo ao projeto.
Adicione os componentes Razor às pastas do projeto denominadas Pages e Shared.
Adicione seus ativos estáticos da Web a uma pasta de projeto denominada wwwroot.
Adicione quaisquer arquivos opcionais _Imports.razor ao seu projeto.

Adicione um BlazorWebView a uma página em seu aplicativo .NET MAUI e aponte-o para a raiz do aplicativo 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>

Modifique o método CreateMauiApp da sua classe MauiProgram para registrar o controle BlazorWebView para uso no seu aplicativo. Para fazer isso, no objeto IServiceCollection, chame o método AddMauiBlazorWebView para adicionar os serviços de exibição da Web do componente à coleção de serviços:

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

Acessar serviços com escopo por meio da interface do usuário nativa

BlazorWebView tem um método TryDispatchAsync que pode chamar um Action<ServiceProvider> especificado de forma assíncrona e passar os serviços com escopo disponíveis nos componentes Razor. Isso permite que o código da interface do usuário nativa acesse serviços com escopo, como 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.
    }
}

Diagnosticando problemas

O BlazorWebView tem um registro em log interno que pode ajudar você a diagnosticar problemas no seu aplicativo Blazor Hybrid. Há duas etapas para habilitar esse registro em log:

Habilite BlazorWebView e componentes relacionados para registrar informações de diagnóstico.
Configure um agente para gravar a saída de log no local em que você pode exibi-la.

Para obter mais informações sobre o registro em log, consulte Registro em log no C# e .NET.

Habilitar o registro em log do BlazorWebView

Toda a configuração do registro em log pode ser realizada como parte do registro do serviço no sistema de injeção de dependência. Para habilitar o máximo do registro em log para BlazorWebView e componentes relacionados no namespace Microsoft.AspNetCore.Components.WebView, adicione o seguinte código ao local no qual os serviços do seu aplicativo estão registrados:

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

Como alternativa, para habilitar o registro em log máximo para cada componente que usa Microsoft.Extensions.Logging, você pode usar o seguinte código:

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

Configurar a saída do registro em log e visualizar a saída

Depois de configurar os componentes para gravar informações de log, você precisa configurar onde os registradores devem gravar os registros e, em seguida, exibir a saída do registro.

Os provedores do registro em log de Depuração gravam a saída usando instruções Debug, e a saída pode ser exibida no Visual Studio.

Para configurar o provedor de registro em log de Depuração, primeiro adicione uma referência em seu projeto ao pacote NuGet Microsoft.Extensions.Logging.Debug. Em seguida, registre o provedor dentro da chamada para AddLogging que você adicionou na etapa anterior, chamando o método de extensão AddDebug:

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

Ao executar o aplicativo no Visual Studio (com a depuração habilitada), você poderá ver a saída da depuração na janela Saída do Visual Studio.

Reproduzir o vídeo em linha no iOS

Para reproduzir o vídeo embutido em um aplicativo híbrido Blazor no iOS, em um BlazorWebView, você deve:

Defina a propriedade UrlLoadingStrategy como OpenInWebView. Isso pode ser feito no manipulador de eventos para o evento UrlLoading:

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

Verifique se a propriedade AllowsInlineMediaPlayback em um objeto Configuration está definida como true. Isso pode ser feito no manipulador de eventos para o evento BlazorWebViewInitializing:
```
private void BlazorWebViewInitializing(object? sender, BlazorWebViewInitializingEventArgs e)
{
#if IOS
    e.Configuration.AllowsInlineMediaPlayback = true;
#endif
}
```

Share via