NativeWebView is the embedded browser control for Avalonia. It derives from NativeControlHost and resolves the active platform backend either from an explicitly supplied backend or from NativeWebViewRuntime.
Current repo runtime status: the embedded native host path is implemented on Windows, macOS, and Linux in the default desktop build. Linux uses a GTK3/WebKitGTK child host on X11. iOS and Android runtime support comes from their platform-targeted backend assemblies rather than the default net10.0 contract build, and Browser support comes from the browser-targeted backend assembly. Browser uses Avalonia Browser native hosting plus an embedded iframe; navigation is real, but script execution and window.chrome.webview-style messaging are limited by same-origin browser security rules. Use NativeWebViewPlatformImplementationStatusMatrix.Get(...) when you need the honest current repo status for the current app build.
Companion surfaces are available when embedding is not the right fit: NativeWebDialog for desktop popup windows and WebAuthenticationBroker for auth callback flows.
Original format.Embedded, GpuSurface, and Offscreen.| Property | Purpose |
|---|---|
Source, CurrentUrl |
Current navigation target and current URL. |
IsInitialized |
Indicates whether backend initialization completed. |
InstanceConfiguration |
Per-instance environment/controller defaults, including proxy and storage directories. |
CanGoBack, CanGoForward |
Navigation history state. |
IsDevToolsEnabled, IsContextMenuEnabled, IsStatusBarEnabled, IsZoomControlEnabled |
Capability-backed runtime toggles. |
ZoomFactor, HeaderString, UserAgentString |
Backend behavior configuration. |
RenderMode, RenderFramesPerSecond |
Render strategy and frame pump rate for composited modes. |
IsUsingSyntheticFrameSource, RenderDiagnosticsMessage, RenderStatistics |
Composition diagnostics and capture statistics. |
MacOsCompositedPassthroughOverride |
Manual passthrough override for macOS composited mode. |
InitializeAsyncNavigate, Reload, Stop, GoBack, GoForwardExecuteScriptAsyncPostWebMessageAsJsonAsync, PostWebMessageAsStringAsyncOpenDevToolsWindowPrintAsync, ShowPrintUiAsyncGetFaviconAsyncTryGetDownloadManagerSetZoomFactor, SetUserAgent, SetHeaderTryGetCommandManager, TryGetCookieManagerMoveFocusSupportsRenderModeSetCompositedPassthroughOverrideCaptureRenderFrameAsync, SaveRenderFrameAsync, SaveRenderFrameWithMetadataAsyncGetRenderStatisticsSnapshot, ResetRenderStatisticsTryGetPlatformHandle, TryGetViewHandle, TryGetControllerHandleCoreWebView2Initialized, CoreWebView2EnvironmentRequested, CoreWebView2ControllerOptionsRequestedNavigationStarted, NavigationCompleted, NavigationHistoryChangedFaviconChangedDownloadStarting, DownloadStarted, DownloadChanged, DownloadCompletedWebMessageReceived, NewWindowRequested, WebResourceRequested, ContextMenuRequestedRequestCustomChrome, RequestParentWindowPosition, BeginMoveDrag, BeginResizeDrag, DestroyRequestedRenderFrameCapturedBackends advertise support through Features. When a backend does not support an operation, capability flags expose that in advance and the method call throws PlatformNotSupportedException if invoked anyway.
Features describe platform capability contracts. They are not a substitute for NativeWebViewPlatformImplementationStatusMatrix when you need to know whether this repository already ships a real native host path for the current target.
NativeWebViewRuntime.EnsureCurrentPlatformRegistered();
WebViewControl.InstanceConfiguration.EnvironmentOptions.UserDataFolder = "./artifacts/webview-a";
WebViewControl.InstanceConfiguration.ControllerOptions.ProfileName = "webview-a";
await WebViewControl.InitializeAsync();
WebViewControl.Navigate("https://example.com");
Use composited-mode diagnostics when you need capture telemetry or airspace investigation:
IsUsingSyntheticFrameSourceRenderDiagnosticsMessageRenderStatisticsGetRenderStatisticsSnapshotCaptureRenderFrameAsyncSaveRenderFrameWithMetadataAsyncResetRenderStatisticsRender statistics expose capture counters and last-frame metadata, including attempt, success, failure, and skip counts together with last failure details.
Sidecar metadata includes FrameId, CapturedAtUtc, RenderMode, Origin, PixelDataLength, and PixelDataSha256.
Use NativeWebViewRenderFrameMetadataSerializer.ReadFromFileAsync to load the sidecar JSON and TryVerifyIntegrity to validate captured frames against the stored integrity fields.
Features.Supports(NativeWebViewFeature.Favicon) before calling GetFaviconAsync.GetFaviconAsync(NativeWebViewFaviconFormat.Original) returns raw favicon bytes when available. SVG favicons are returned as image/svg+xml bytes and are not rasterized by the control.Features.Supports(NativeWebViewFeature.Downloads) or TryGetDownloadManager before showing download UI.DownloadStarting is raised before the transfer starts. Use GetDeferral() when showing an async save-location picker, then set DestinationPath or set Cancel = true.NativeWebViewDownloadSnapshot values from DownloadStarted, DownloadChanged, and DownloadCompleted to update UI. Snapshots include URI, suggested filename, destination, state, bytes, progress, transfer rate, timestamps, error details, and action capability flags.NativeWebViewPlatformImplementationStatusMatrix.Get(platform) before assuming the current target has a real embedded runtime path.Features.Supports(NativeWebViewFeature.ProxyConfiguration) before relying on runtime proxy application.NativeWebView controls, on macOS 14+, and on iOS 17+ when the iOS backend is built with the .NET 8 Apple workload.http, https, and socks5 proxy servers plus bypass domains.http, https, and socks5 proxy servers, credentials, and bypass domains on iOS 17+.AdditionalBrowserArguments.WebView instance by this repo.Proxy.AutoConfigUrl is not applied by the current Apple runtime integrations in this repo.