1. Home
  2. Docs
  3. Platforms
  4. Windows

Windows

Backend

  • Package: NativeWebView.Platform.Windows
  • Platform enum: NativeWebViewPlatform.Windows
  • Native engine: Microsoft Edge WebView2

Current Repo Implementation Status

  • NativeWebView: implemented. The control now creates a real child HWND and WebView2 controller when hosted through the Avalonia NativeWebView control.
  • NativeWebDialog: implemented. The backend now creates a real top-level HWND and hosts the WebView2 runtime inside it.
  • WebAuthenticationBroker: implemented through the Windows dialog runtime and a WebView2-backed auth window.
  • Check NativeWebViewPlatformImplementationStatusMatrix.Get(NativeWebViewPlatform.Windows) in code when you need the honest current repo status.

Platform Engine Capability

  • Embedded view
  • GPU surface rendering
  • Offscreen rendering
  • Dialog
  • Authentication broker
  • DevTools, context menu, status bar, zoom
  • Printing and print UI
  • New window and resource request interception
  • Environment and controller options
  • Native handles
  • Cookie manager and command manager
  • Downloads

Registration

factory.UseNativeWebViewWindows();

Diagnostics Notes

Use NATIVEWEBVIEW_WEBVIEW2_RUNTIME_PATH when you need an explicit runtime path override. If it is set, the path must exist.

Windows apps that host NativeWebView through Avalonia NativeControlHost need an application manifest with supported OS declarations. The desktop sample now includes app.manifest; custom Windows hosts should ship the same kind of manifest to avoid the Avalonia child-window creation failure.

When WebView2 rejects controller options with an invalid-argument failure, the Windows backend now retries controller creation without those options so initialization can still succeed on runtimes that do not accept the requested profile or locale settings.

Proxy Notes

  • WebView2 can be configured via environment options and Chromium proxy arguments.
  • NativeWebViewWindowsProxyArgumentsBuilder converts shared proxy options into AdditionalBrowserArguments payloads for WebView2-style integrations.
  • The Windows NativeWebView and NativeWebDialog runtime paths apply per-instance proxy settings by merging them into WebView2 AdditionalBrowserArguments.

Authentication Notes

  • The current Windows WebAuthenticationBroker implementation uses a dedicated dialog-hosted WebView2 session and completes when navigation reaches the callback scheme/host/path.
  • UseHttpPost is not currently implemented on the Windows runtime path.

Download Notes

  • Windows advertises NativeWebViewFeature.Downloads for NativeWebView and NativeWebDialog.
  • Downloads use WebView2 DownloadStarting and native download operation events.
  • Destination selection is handled through DownloadStarting; set DestinationPath or cancel before the WebView2 deferral completes.
  • Progress, completion, cancellation, failure, and native pause/resume are surfaced through download item snapshots when WebView2 supports the action.
  • Restart is not advertised in this iteration.