ASP.NET Core Blazor Hybrid

本文介绍 ASP.NET Core Blazor Hybrid，可以通过它在 ASP.NET Core 应用中使用 .NET 生成交互式客户端 Web UI。

使用 Blazor Hybrid 将桌面和移动本机客户端框架与 .NET 和 Blazor 结合使用。

在 Blazor Hybrid 应用中，Razor 组件在设备上本机运行。 组件通过本地互操作通道呈现到嵌入式 Web View 控件。 组件不在浏览器中运行，并且不涉及 WebAssembly。 Razor 组件可快速加载和执行代码，组件可通过 .NET 平台完全访问设备的本机功能。 Web View 中呈现的组件样式与平台相关，可能需要你使用自定义样式表来说明不同平台之间的呈现差异。

Blazor Hybrid 文章涵盖与将 Razor 组件集成到本机客户端框架相关的主题。

Blazor Hybrid 应用和 .NET MAUI

Blazor Hybrid 支持内置于 .NET Multi-platform App UI (.NET MAUI) 框架中。 .NET MAUI 包含 BlazorWebView 控件，该控件运行将 Razor 组件呈现到嵌入式 Web View 中。 通过结合使用 .NET MAUI 和 Blazor，可以跨移动设备、桌面设备和 Web 重复使用一组 Web UI 组件。

具有 WPF 和 Windows 窗体的 Blazor Hybrid 应用

Blazor Hybrid 应用可以使用 Windows Presentation Foundation (WPF) 和 Windows 窗体构建。 Blazor 为这两个框架（WPF BlazorWebView、Windows 窗体 BlazorWebView）提供 BlazorWebView 控件。 Razor 组件在 Windows 桌面本机运行并呈现到嵌入式 Web View。 通过在 WPF 和 Windows 窗体中使用 Blazor，可以将新的 UI 添加到现有的 Windows 桌面应用，这些应用可以跨具有 .NET MAUI 的平台或在 Web 上重复使用。

Web View 配置

Blazor Hybrid 通过 BlazorWebView 控件的事件公开不同平台的基础 Web View 配置：

• BlazorWebViewInitializing 提供对用于在每个平台上创建 Web View 的设置的访问权限（如果设置可用）。
• BlazorWebViewInitialized 提供对 Web View 的访问权限以允许对设置执行进一步的配置。

使用每个平台上的首选模式将事件处理程序附加到事件以执行自定义代码。

API 文档：

• .NET MAUI
  • BlazorWebViewInitializing
  • BlazorWebViewInitialized
• WPF
  • BlazorWebViewInitializing
  • BlazorWebViewInitialized
• Windows 窗体
  • BlazorWebViewInitializing
  • BlazorWebViewInitialized

Windows 窗体和 WPF 应用中未经处理的异常

本部分仅适用于 Windows 窗体和 WPF Blazor Hybrid 应用。

在 System.AppDomain.CurrentDomain 属性上为 UnhandledException 创建回调。 以下示例使用编译器指令显示一个 MessageBox，用于提醒用户发生错误或向开发人员显示错误信息。 在 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)
};

全球化和本地化

本部分仅适用于 .NET MAUIBlazor Hybrid 应用。

.NET MAUI 基于设备的环境信息配置 CurrentCulture 和 CurrentUICulture。

IStringLocalizer 和 Microsoft.Extensions.Localization 命名空间中的其他 API 通常按预期运行，以及会进行依赖于用户区域性的全球化格式设置、分析和绑定。

在运行时以动态方式更改应用区域性时，必须重新加载应用以反映区域性更改，这会重新呈现根组件并将新的区域性传递给重新呈现的子组件。

.NET 的资源系统支持将本地化图像（作为 blob）嵌入到应用中，但 Blazor Hybrid 目前无法在 Razor 组件中显示嵌入图像。 即使用户使用 ResourceManager 将图像的字节读取到 Stream 中，框架当前也不支持在 Razor 组件中呈现检索到的图像。

包含本地化图像的平台特定方法是 .NET 的资源系统的一项功能，但 .NET MAUIBlazor Hybrid 应用中 Razor 组件的浏览器元素无法与此类图像进行交互。

有关详细信息，请参阅以下资源：

• Xamarin.Forms 字符串和图像本地化：本指南通常适用于 Blazor Hybrid 应用。 目前并非所有方案均受支持。
• Blazor 图像组件，用于显示无法通过 HTTP 终结点访问的图像 (dotnet/aspnetcore #25274)

从本机 UI 访问范围内服务

BlazorWebView 具有一个 TryDispatchAsync 方法，该方法以异步方式调用指定 Action<ServiceProvider>，并传入 Razor 组件中可用的范围内服务。 这样，本机 UI 中的代码就可以访问范围内服务，例如 NavigationManager：

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

    if (!wasDispatchCalled)
    {
        ...
    }
}

如果 wasDispatchCalled 是 false，请考虑在未调度调用时执行什么操作。 通常，调度不应失败。 如果失败，OS 资源可能会耗尽。 如果资源耗尽，请考虑记录消息、引发异常，并可能提醒用户。

其他资源

• ASP.NET Core Blazor Hybrid 教程
• .NET Multi-platform App UI （.NET MAUI）
• Windows Presentation Foundation (WPF)
• Windows 窗体