Skip to main content

Blazor WebView Guide

InfiniLore.InfiniFrame.BlazorWebView integrates a full Blazor WebAssembly-style application into a native window with no HTTP server required. The Blazor runtime runs entirely in-process.

Contents​

How It Works​

InfiniFrame serves Blazor resources from an internal origin (app://localhost/) and handles requests inside the native host. Blazor component files, JavaScript, and CSS are served from an IFileProvider backed by your wwwroot/ folder. There is no external ASP.NET server required; all communication happens through the native browser bridge.

Platform notes:

  • Windows uses WebView2 and requires custom-scheme registration support (ICoreWebView2EnvironmentOptions4) to allow top-level app://localhost/... navigation.
  • Linux and macOS use WebKit-based engines and do not depend on WebView2.
  • On Windows, if the WebView2 runtime does not support custom-scheme registration, startup fails fast with a clear error asking for a WebView2 runtime update.

Project Setup​

Your project must use the Razor SDK:

<Project Sdk="Microsoft.NET.Sdk.Razor">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <OutputType>Exe</OutputType>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="InfiniLore.InfiniFrame.BlazorWebView" Version="0.1.1" />
  </ItemGroup>
</Project>

wwwroot/index.html​

A minimal host page:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />
    <link rel="stylesheet" href="app.css" />
</head>
<body>
    <div id="app">Loading...</div>
    <div id="blazor-error-ui" style="display:none">
        An unhandled error has occurred.
    </div>
    <script src="_framework/blazor.webview.js"></script>
</body>
</html>

Program.cs​

using InfiniFrame.BlazorWebView;
using Microsoft.Extensions.DependencyInjection;

var builder = InfiniFrameBlazorAppBuilder.CreateDefault(args, w => w
    .SetTitle("My Blazor App")
    .SetSize(1280, 720)
    .Center()
    .SetChromeless(true)     // Optional: remove native title bar
);

// Register services (same as a standard Blazor or ASP.NET Core app)
builder.Services.AddSingleton<MyDataService>();
builder.Services.AddScoped<IMyRepository, MyRepository>();

// Register root components (these map to elements in index.html)
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Build().Run();

Run() blocks until the window is closed and then disposes all services.

Available Builder API​

InfiniFrameBlazorAppBuilder exposes three properties for configuration:

PropertyTypeDescription
WindowBuilderIInfiniFrameWindowBuilderFluent window configuration; all options from the generated C# API reference
ServicesIServiceCollectionStandard .NET DI container
RootComponentsRootComponentListMaps Blazor components to CSS selectors in index.html

Configuring the window separately​

var builder = InfiniFrameBlazorAppBuilder.CreateDefault();

builder.WithInfiniFrameWindowBuilder(w => w
    .SetTitle("Configured Later")
    .SetDevToolsEnabled(true)
);

Dependency Injection​

The following services are automatically registered and available for injection:

ServiceLifetimeDescription
IInfiniFrameWindowSingletonThe native window instance
IInfiniFrameJsScopedJavaScript interop utilities
HttpClientScopedPreconfigured for in-process requests
DispatcherSingletonBlazor's component dispatcher

Injecting the window in a component​

@inject IInfiniFrameWindow Window

<button @onclick="Minimize">Minimize</button>
<button @onclick="Close">Close</button>

@code {
    void Minimize() => Window.Invoke(() => { /* window ops must be on UI thread */ });
    void Close() => Window.Close();
}

Custom File Provider​

By default, files are served from {AppBaseDirectory}/wwwroot/. You can supply a custom IFileProvider for embedded resources, encrypted assets, or virtual file systems:

using Microsoft.Extensions.FileProviders;

var embeddedProvider = new EmbeddedFileProvider(typeof(Program).Assembly, "MyApp.wwwroot");

var builder = InfiniFrameBlazorAppBuilder.CreateDefault(
    fileProvider: embeddedProvider,
    args: args
);

External JS Modules and Trusted Origins​

If your app imports scripts from external origins (for example import ... from "https://cdn.example/..."), keep WebSecurity enabled and explicitly trust those origins.

var app = InfiniFrameBlazorAppBuilder.CreateDefault(windowBuilder: wb => {
    wb.AddTrustedOrigin("https://xyz");
    // add redirects too if needed (e.g. cdn.jsdelivr.net, unpkg.com, etc.)
});

For multiple hosts:

var app = InfiniFrameBlazorAppBuilder.CreateDefault(windowBuilder: wb => {
    wb.AddTrustedOrigin("https://xyz");
    wb.AddTrustedOrigin("https://cdn.jsdelivr.net");
    wb.AddTrustedOrigin("https://unpkg.com");
});

To disable origin checks entirely (not recommended for production), opt in explicitly:

var app = InfiniFrameBlazorAppBuilder.CreateDefault(windowBuilder: wb => {
    wb.SetTrustAllOrigins(true);
});

Do not use .SetWebSecurityEnabled(false) as a workaround for this scenario.

Error Handling​

Unhandled exceptions in the process are caught automatically and shown as a native message dialog:

Fatal exception
System.NullReferenceException: Object reference not set...

To customize error handling, register a handler before Build():

AppDomain.CurrentDomain.UnhandledException += (_, e) => {
    // Custom logging or reporting
};

HttpClient​

An HttpClient is registered automatically with BaseAddress set to the internal app base URI. This lets you make in-process requests to your static assets or call external APIs:

@inject HttpClient Http

@code {
    protected override async Task OnInitializedAsync() {
        var data = await Http.GetFromJsonAsync<MyData[]>("data/mydata.json");
    }
}

Lifecycle​

InfiniFrameBlazorAppBuilder.CreateDefault()
    ↓
Configure Services & RootComponents
    ↓
.Build()  ← Registers the custom scheme, creates the window
    ↓
.Run()    ← Starts the Blazor runtime, blocks until window closes
    ↓
DisposeAsync()  ← Disposes all services

Custom Window Chrome​

Combine with InfiniLore.InfiniFrame.Blazor for a fully custom title bar.

See the Custom Window Chrome Guide for details.

Examples​

  • InfiniFrameExample.BlazorWebView (examples/InfiniFrameExample.BlazorWebView) - minimal Blazor app with window configuration and Serilog
  • InfiniFrameExample.BlazorWebView.MultiWindowSample (examples/InfiniFrameExample.BlazorWebView.MultiWindowSample) - multiple windows each hosting a different Blazor component