PhotinoX.Blazor

Blazor integration for PhotinoX (native OS WebView host).

• Windows: WebView2
• macOS: WKWebView
• Linux: WebKitGTK 4.1

Note: PhotinoX.Blazor is an independent fork of tryphotino/photino.Blazor under the Apache‑2.0 license and is not affiliated with the original project or organization.

---

Quick start

[STAThread]
static void Main(string[] args)
{
    var appBuilder = PhotinoBlazorAppBuilder.CreateDefault(args);

    appBuilder.Services
        .AddLogging();

    // Register the root component and selector for the main window.
    appBuilder.RootComponents.Add<App>("app");

    var app = appBuilder.Build();

    // Customize the native Photino window.
    app.MainBlazorWindow.Window
        .SetIconFile("favicon.ico")
        .SetTitle("PhotinoX Blazor Sample");

    AppDomain.CurrentDomain.UnhandledException += (_, error) =>
    {
        app.MainBlazorWindow.Window.ShowMessage(
            "Fatal exception",
            error.ExceptionObject?.ToString() ?? "Unknown fatal exception.");
    };

    app.Run();
}

Application and window model

PhotinoX.Blazor separates application-level services from window-level Blazor hosting:

• PhotinoBlazorApp owns the shared service provider and application lifecycle.
• PhotinoBlazorWindow represents one native Photino window hosting Blazor content.
• Each PhotinoBlazorWindow has its own root components, WebView manager, Blazor dispatcher/synchronization context, and message pipeline.

Window-scoped services are isolated through a per-window service provider, so HttpClient, resource handling, root components, and WebView manager state are scoped to each window.

This makes multi-window scenarios explicit and avoids sharing window-specific Blazor state between native windows.

Root components should be configured before the corresponding PhotinoBlazorWindow.Show() call.

Application scheme

PhotinoX.Blazor uses the app custom scheme on Windows, macOS, and Linux. The upstream Windows http workaround is no longer used because PhotinoX.Native now supports custom scheme navigation on WebView2.

URL loading

PhotinoX.Blazor supports BlazorWebView-style URL loading policy through PhotinoBlazorWindow.UrlLoading.

Normal top-level navigation raises UrlLoading, allowing the app to choose whether a URL should load inside the WebView, open externally, or be canceled.

app.MainBlazorWindow.UrlLoading += (_, e) =>
{
    if (e.Url.Scheme is "http" or "https")
        e.UrlLoadingStrategy = UrlLoadingStrategy.OpenExternally;
};

Default behavior:

• app-origin URLs load inside the WebView;
• external HTTP/HTTPS URLs open in the system browser;
• target="_blank" and window.open(...) are handled as new-window requests and open externally.

Key differences from Photino.Blazor

Area	Photino.Blazor	PhotinoX.Blazor
Application model	Main-window host built around PhotinoWindow.WaitForClose().	Runs on top of the PhotinoApplication model.
Window hosting	Main window, root components, WebView manager, and services are mostly application-level.	Each PhotinoBlazorWindow has window-scoped root components, resource handling, WebView manager state, and Blazor dispatcher/synchronization context.
Application scheme	Uses http on Windows and app on Linux/macOS.	Uses app on all supported platforms.
URL loading policy	No BlazorWebView-style UrlLoading API for intercepting normal link navigation.	Adds UrlLoading, UrlLoadingEventArgs, and UrlLoadingStrategy for intercepting top-level navigation and choosing OpenInWebView, OpenExternally, or CancelLoad.

Multiple windows

[STAThread]
static void Main(string[] args)
{
    var appBuilder = PhotinoBlazorAppBuilder.CreateDefault(args);

    appBuilder.Services
        .AddLogging();

    appBuilder.RootComponents.Add<Window1>("app");

    var app = appBuilder.Build();

    var window1 = app.MainBlazorWindow;
    window1.Window
        .SetTitle("Window 1")
        .Load("window1.html");

    var window2 = app.CreateWindow<Window2>("app");
    window2.Window
        .SetTitle("Window 2")
        .Load("window2.html");

    window1.Window.RegisterCreatedHandler((_, _) =>
    {
        window2.Show();
    });

    app.Run();
}

Core (ecosystem)

• PhotinoX - managed .NET wrapper around the native layer.
• PhotinoX.App - Application composition layer for PhotinoX desktop applications.
• PhotinoX.Native - native binaries for Windows/macOS/Linux.
• PhotinoX.Server - optional local static-file server for SPA/static assets.
• PhotinoX.Samples - sample projects showcasing common scenarios.

---

Install

dotnet add package PhotinoX.Blazor

PhotinoX.Native provides the native WebView host binaries and must be available for the target runtime identifier.

Package targets net8.0; net9.0; net10.0.

Samples

• https://github.com/ivanvoyager/PhotinoX.Blazor/tree/master/Samples

Requirements

• .NET 10 SDK (build)
• Target frameworks: net8.0; net9.0; net10.0 (package supports all three)
• Runtime deps: see PhotinoX.Native (runtimes/<rid>/native/)
• Windows: Microsoft Edge WebView2 Runtime
  https://learn.microsoft.com/microsoft-edge/webview2/
• macOS: WKWebView (system WebKit)
  https://developer.apple.com/documentation/webkit/wkwebview/
• Linux: WebKitGTK 4.1 (runtime + dev packages)
  https://webkitgtk.org/

Build from source

dotnet restore Photino.Blazor/PhotinoX.Blazor.csproj
dotnet build   Photino.Blazor/PhotinoX.Blazor.csproj -c Release
dotnet pack    Photino.Blazor/PhotinoX.Blazor.csproj -c Release -o artifacts

CI: see .github/workflows/build.yml (build + pack + upload .nupkg/.snupkg).

Contributing

Issues and PRs are welcome. Keep PRs focused, minimal, and consistent with the rest of PhotinoX.

License

PhotinoX.Blazor is licensed under Apache‑2.0.