maui-blazor-hybrid

MAUI Blazor Hybrid

Use this skill when a MAUI app hosts Razor components or an embedded web surface inside a native app.

Workflow

1. Inspect MauiProgram.cs, .razor files, wwwroot, and XAML pages that host BlazorWebView or HybridWebView.
2. Choose the right host:
   • BlazorWebView for Razor components rendered inside MAUI.
   • HybridWebView for HTML/JavaScript content that exchanges messages with .NET without using the Blazor component model.
3. Register Blazor Hybrid services in MauiProgram.cs.
4. Keep native services in MAUI DI and consume them from Razor through DI.
5. Put static web assets under wwwroot or referenced Razor class libraries.
6. Use JS/.NET interop through documented APIs, not platform WebView internals. For HybridWebView raw messaging, always show SendRawMessage, RawMessageReceived, a JSON DTO contract, and a source-generated JsonSerializerContext/System.Text.Json path when trimming, NativeAOT, Release trimming, or trimming-safe messaging is part of the request. Do not answer with only raw strings or DynamicDependency.
7. Review trimming and NativeAOT risks for reflection, serialization, and JS interop payloads.
8. Use DevFlow CDP tools to inspect WebView DOM, console logs, CDP screenshots, and route state when debugging. For Blazor Hybrid stale route/DOM answers, explicitly name maui_cdp_webviews, maui_cdp_source or maui_cdp_evaluate, and at least one evidence tool: maui_cdp_screenshot or maui_logs.

BlazorWebView Pattern

builder.Services.AddMauiBlazorWebView();

<BlazorWebView HostPage="wwwroot/index.html">
    <BlazorWebView.RootComponents>
        <RootComponent Selector="#app" ComponentType="{x:Type local:Routes}" />
    </BlazorWebView.RootComponents>
</BlazorWebView>

Razor components can inject MAUI services registered in the same DI container. Keep platform work behind interfaces so components remain testable. The root component type depends on the template; newer templates often use Routes, while older templates may use Main.