ASP.NET Core Blazor Hybrid

發行項
11/13/2024

注意

這不是這篇文章的最新版本。如需目前的版本，請參閱本文的 .NET 9 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支援原則。如需目前版本，請參閱本文的 .NET 8 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前的版本，請參閱本文的 .NET 9 版本。

本文說明 ASP.NET Core Blazor Hybrid，這是在 ASP.NET Core 應用程式中使用 .NET 建置互動式用戶端 Web UI 的方式。

使用 Blazor Hybrid 搭配 .NET 和 Blazor 混合桌面與行動原生用戶端架構。

在 Blazor Hybrid 應用程式中，會在裝置上以原生方式執行 Razor 元件。元件會透過本機 Interop 通道轉譯至內嵌的 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 包含允許將 Razor 元件轉譯成內嵌 Web View 的 BlazorWebView 控制項。藉由將 .NET MAUI 與 Blazor 一起使用，您可以跨行動裝置、桌面和 Web 重複使用一組 Web UI 元件。

具有 WPF 和 Windows Forms 的 Blazor Hybrid 應用程式

Blazor Hybrid 應用程式可以使用 Windows Presentation Foundation (WPF) 和 Windows Forms 來建置。 Blazor 提供這兩個架構的 BlazorWebView 控制項 (WPFBlazorWebView、Windows FormsBlazorWebView)。 Razor 元件會在 Windows 桌面中以原生方式執行，並轉譯成內嵌的 Web View。在 WPF 和 Windows Forms 中使用 Blazor，可讓您將新的 UI 新增至現有的 Windows 傳統型應用程式，而這些應用程式可在具有 .NET MAUI 或網路上的平台之間重複使用。

Web View 設定

Blazor Hybrid 會透過 BlazorWebView 控制項的事件來公開不同平台的基礎 Web View 設定：

如果設定可供使用，則 BlazorWebViewInitializing 會提供存取每個平台上用來建立 Web View 的設定。
BlazorWebViewInitialized 可讓您存取 Web View，以允許進一步設定設定值。

在每個平台上使用慣用的模式將事件處理常式附加至事件，以執行您的自訂程式碼。

API 文件：

.NET MAUI
- BlazorWebViewInitializing
- BlazorWebViewInitialized
WPF
- BlazorWebViewInitializing
- BlazorWebViewInitialized
Windows Forms
- BlazorWebViewInitializing
- BlazorWebViewInitialized

Windows Forms 和 WPF 應用程式中未處理的例外狀況

本節僅適用於 Windows Forms 和 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。

Microsoft.Extensions.Localization 命名空間中的 IStringLocalizer 和其他 API 通常會如預期般運作，以及具有依賴使用者文化特性 (Culture) 的全球化格式、剖析和繫結。

在執行階段動態變更應用程式文化特性 (Culture) 時，必須重載應用程式以反映文化特性 (Culture) 的變更，這會負責根元件的重新轉譯，並將新的文化特性 (Culture) 傳遞至重新轉譯的子元件。

.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 資源可能會用盡。如果資源用盡，請考慮記錄訊息、擲回例外狀況，並可能向使用者發出警示。

共用方式為