.NET MAUI Blazor Hybrid: How the Architecture Works

Blazor Hybrid combines a native .NET MAUI application with Razor components. Unlike Blazor WebAssembly, the Razor components in a Hybrid application run inside the native application process and render through a platform WebView.

🚀 Open this concept in the MAUI Playground

Basic Architecture

• MAUI host: owns the native application lifecycle.
• BlazorWebView: hosts the Razor UI.
• Razor components: provide reusable interactive UI.
• .NET services: can be shared between native and Razor layers.
• Platform APIs: expose device-specific capabilities.

Why Use Hybrid?

Hybrid is useful when an application needs a rich Razor UI but also needs native capabilities such as local storage, device APIs, desktop integration, or mobile features.

Dependency Injection

Shared services can be registered with the MAUI application's dependency injection container and injected into Razor components. This allows authentication, configuration, API clients, and application state to be centralized.

JavaScript Interop

Blazor components can use JavaScript interop for browser-side behavior inside the WebView. Keep interop calls isolated so that platform-specific details do not leak into every component.

State Management

Be deliberate about service lifetimes. Shared mutable state stored in a singleton can be convenient, but it also needs clear ownership and synchronization. Refreshing a page or restarting the native process may change what state survives.

Common Mistakes

• Assuming Hybrid behaves exactly like Blazor Server.
• Putting every native operation directly inside Razor components.
• Using global mutable state without defining its lifetime.
• Forgetting to dispose long-lived event subscriptions or JavaScript resources.

Conclusion

.NET MAUI Blazor Hybrid is a strong option when you want reusable Razor UI together with native application capabilities. A clean separation between UI, services, native integrations, and state management keeps the project maintainable as it grows.

Back to .NET MAUI Tutorials