1. Home
  2. Docs
  3. Getting Started
  4. Installation

Installation

Core Package Setup

Install the Avalonia control package plus the platform package that matches the runtime you ship:

dotnet add package NativeWebView
dotnet add package NativeWebView.Platform.Windows

Replace NativeWebView.Platform.Windows with NativeWebView.Platform.macOS, NativeWebView.Platform.Linux, NativeWebView.Platform.iOS, NativeWebView.Platform.Android, or NativeWebView.Platform.Browser as needed.

Package installation and backend registration are broader than any single surface's runtime status. Check NativeWebViewPlatformImplementationStatusMatrix.Get(...) before treating a specific NativeWebView, NativeWebDialog, or WebAuthenticationBroker target as production-ready.

Optional facades:

dotnet add package NativeWebView.Dialog
dotnet add package NativeWebView.Auth
  • NativeWebView.Dialog is meaningful on the desktop runtime paths: Windows, macOS, and Linux.
  • NativeWebView.Auth is implemented across the current Windows, macOS, Linux, iOS, Android, and Browser runtime paths.
  • iOS and Android runtime support comes from their platform-targeted backend assemblies rather than the default net8.0 contract build.

Package Layout

Package Purpose
NativeWebView Avalonia control facade API.
NativeWebView.Core Shared contracts, controllers, feature model, and backend factory.
NativeWebView.Dialog Dialog facade API.
NativeWebView.Auth Web authentication broker facade API.
NativeWebView.Interop Native handle contracts and structs.
NativeWebView.Platform.Windows Windows backend registration and implementation.
NativeWebView.Platform.macOS macOS backend registration and implementation.
NativeWebView.Platform.Linux Linux backend registration and implementation.
NativeWebView.Platform.iOS iOS backend registration and implementation.
NativeWebView.Platform.Android Android backend registration and implementation.
NativeWebView.Platform.Browser Browser backend registration and implementation.

Backend Registration

Register the backend in application startup or composition root code:

using NativeWebView.Core;
using NativeWebView.Platform.Windows;

var factory = new NativeWebViewBackendFactory();
factory.UseNativeWebViewWindows();

This registers the Windows capability contract, and the current repo now also ships real Windows runtime paths for NativeWebView, NativeWebDialog, and WebAuthenticationBroker.

If you rely on default constructors, runtime auto-registration is available:

NativeWebViewRuntime.EnsureCurrentPlatformRegistered();

Readiness Validation

Validate prerequisites before creating the first control:

var diagnostics = factory.GetPlatformDiagnosticsOrDefault(NativeWebViewPlatform.Windows);
NativeWebViewDiagnosticsValidator.EnsureReady(diagnostics);

This is the recommended startup guard in both samples and CI.

If your application requires the real embedded NativeWebView control runtime, pair diagnostics with:

var implementationStatus = NativeWebViewPlatformImplementationStatusMatrix.Get(NativeWebViewPlatform.Windows);
if (implementationStatus.EmbeddedControl != NativeWebViewRepositoryImplementationStatus.RuntimeImplemented)
{
    throw new PlatformNotSupportedException("Embedded control runtime is not implemented for this target yet.");
}

Avalonia Integration Notes

Add the XML namespace in XAML:

xmlns:nwv="clr-namespace:NativeWebView.Controls;assembly=NativeWebView"

Then place the control in layout markup:

<nwv:NativeWebView x:Name="WebViewControl" />

The default constructor uses NativeWebViewRuntime to resolve the current platform backend.

Next