ASP.NET Core Blazor Hybrid

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Este artigo explica o Blazor Hybrid no ASP.NET Core, uma maneira de criar a IU da Web interativa do lado do cliente com o .NET em um aplicativo ASP.NET Core.

Use Blazor Hybrid para combinar estruturas de cliente nativas de desktop e móveis com .NET e Blazor.

Em um aplicativo Blazor Hybrid, os componentes Razor são executados nativamente no dispositivo. Os componentes são renderizados em um controle Web View inserido por meio de um canal de interoperabilidade local. Os componentes não são executados no navegador e o WebAssembly não está envolvido. Os componentes Razor carregam e executam o código rapidamente, e os componentes têm acesso total aos recursos nativos do dispositivo por meio da plataforma .NET. Os estilos de componente renderizados em uma Web View são dependentes da plataforma e podem exigir que você dê conta das diferenças de renderização entre plataformas usando folhas de estilos personalizadas.

Os artigos Blazor Hybrid abordam assuntos relativos à integração de componentes Razor em estruturas de cliente nativas.

Aplicativos Blazor Hybrid com .NET MAUI

O suporte para Blazor Hybrid é integrado à estrutura .NET Multi-platform App UI (.NET MAUI). .NET MAUI inclui o controle BlazorWebView que permite renderizar componentes Razor em um Web View inserido. Ao usar o .NET MAUI e o Blazor juntos, você pode reutilizar um conjunto de componentes de interface do usuário da Web em dispositivos móveis, desktops e Web.

Aplicativos Blazor Hybrid com WPF e Windows Forms

Aplicativos Blazor Hybrid podem ser criados com a Windows Presentation Foundation (WPF) e o Windows Forms. O Blazor fornece controles de BlazorWebView para as duas estruturas (WPF BlazorWebView, Windows Forms BlazorWebView). Os componentes Razor são executados nativamente na área de trabalho do Windows e renderizados em um Web View inserido. Usar Blazor na WPF e no Windows Forms permite adicionar uma nova interface do usuário aos aplicativos da área de trabalho existentes do Windows que podem ser reutilizados em plataformas com .NET MAUI ou na Web.

Configuração de Web View

Blazor Hybrid expõe a configuração Web View subjacente para diferentes plataformas por meio de eventos do controle BlazorWebView:

  • BlazorWebViewInitializing fornece acesso às configurações usadas para criar o Web View em cada plataforma, se as configurações estiverem disponíveis.
  • BlazorWebViewInitialized fornece acesso ao Web View para permitir a definição adicional das configurações.

Use os padrões preferenciais em cada plataforma para anexar manipuladores de eventos aos eventos para executar o código personalizado.

Documentação da API:

Exceções sem tratamento em aplicativos Windows Forms e WPF

Esta seção só se aplica a aplicativos Blazor Hybrid para Windows Forms e WPF.

Crie um retorno de chamada para UnhandledException na propriedade System.AppDomain.CurrentDomain. O exemplo a seguir usa uma diretiva do compilador para exibir um MessageBox que alerta o usuário de que ocorreu um erro ou mostra as informações de erro para o desenvolvedor. Registre as informações de erro em error.ExceptionObject.

AppDomain.CurrentDomain.UnhandledException += (sender, error) =>
{
#if DEBUG
    MessageBox.Show(text: error.ExceptionObject.ToString(), caption: "Error");
#else
    MessageBox.Show(text: "An error has occurred.", caption: "Error");
#endif
    
    // Log the error information (error.ExceptionObject)
};

Globalização e localização

Esta seção só se aplica a aplicativos .NET MAUIBlazor Hybrid.

.NET MAUI configura o CurrentCulture e CurrentUICulture com base nas informações de ambiente do dispositivo.

IStringLocalizer e outras APIs no namespace Microsoft.Extensions.Localization geralmente funcionam conforme o esperado, juntamente com a formatação, análise e associação de globalização que dependem da cultura do usuário.

Ao alterar dinamicamente a cultura do aplicativo em runtime, o aplicativo deve ser recarregado para refletir a alteração na cultura, que cuida da nova renderização do componente raiz e da passagem da nova cultura para componentes filho renderizados de novo.

O sistema de recursos do .NET dá suporte à inserção de imagens localizadas (como blobs) em um aplicativo, mas o Blazor Hybrid não pode exibir as imagens inseridas em componentes do Razor no momento. Mesmo que um usuário leia os bytes de uma imagem em um Stream usando ResourceManager, a estrutura não dá suporte atualmente à renderização da imagem recuperada em um componente do Razor.

Uma abordagem específica da plataforma para incluir imagens localizadas é um recurso do sistema de recursos do NET, mas os elementos do navegador de um componente do Razor em um aplicativo .NET MAUIBlazor Hybrid não são capazes de interagir com essas imagens.

Para saber mais, consulte os recursos a seguir:

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

O BlazorWebView tem um método TryDispatchAsync que chama um Action<ServiceProvider> especificado de maneira assíncrona e passa os serviços com escopo disponíveis em componentes Razor. Isso permite que o código da interface do usuário nativa acesse serviços com escopo, como NavigationManager:

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

    if (!wasDispatchCalled)
    {
        ...
    }
}

Quando wasDispatchCalled for false, considere o que fazer se a chamada não tiver sido enviada. O envio não costuma falhar. Se falhar, os recursos do sistema operacional poderão ser esgotados. Se os recursos forem esgotados, considere registrar uma mensagem em log, gerar uma exceção e, talvez, alertar o usuário.

Recursos adicionais