32. Platform services, embedding, and native interop

Goal

Why this matters

Prerequisites

1. Platform abstractions overview

Avalonia abstracts windowing via interfaces in Avalonia.Controls.Platform and Avalonia.Platform:

Interface Location Purpose
IWindowingPlatform external/Avalonia/src/Avalonia.Controls/Platform/IWindowingPlatform.cs Creates windows, embeddable top levels, tray icons
INativeControlHostImpl platform backends (Win32, macOS, iOS, Browser) Hosts native HWND/NSView/UIViews inside Avalonia (NativeControlHost)
ITrayIconImpl backend-specific Implements tray icons (PlatformManager.CreateTrayIcon)
IPlatformStorageProvider, ILauncher Avalonia.Platform.Storage File pickers, launchers across platforms
IApplicationPlatformEvents Avalonia.Controls.Platform System-level events (activation, protocol handlers)

PlatformManager coordinates these services and surfaces high-level helpers (tray icons, dialogs). Check TopLevel.PlatformImpl to access backend-specific features.

2. Hosting native controls inside Avalonia

NativeControlHost (external/Avalonia/src/Avalonia.Controls/NativeControlHost.cs) lets you wrap native views:

Example (Win32 HWND):

public class Win32WebViewHost : NativeControlHost
{
    protected override IPlatformHandle CreateNativeControlCore(IPlatformHandle parent)
    {
        var hwnd = Win32Interop.CreateWebView(parent.Handle);
        return new PlatformHandle(hwnd, "HWND");
    }

    protected override void DestroyNativeControlCore(IPlatformHandle control)
    {
        Win32Interop.DestroyWindow(control.Handle);
    }
}

Guidelines:

3. Embedding Avalonia inside native hosts

EmbeddableControlRoot (external/Avalonia/src/Avalonia.Controls/Embedding/EmbeddableControlRoot.cs) wraps a TopLevel that can live in non-Avalonia environments:

Examples:

Interop tips:

MicroCom bridges for Windows interop

Avalonia relies on MicroCom to generate COM-compatible wrappers. When embedding on Windows (drag/drop, menus, Win32 interop):

You rarely need to touch MicroCom directly, but understanding it helps when diagnosing drag/drop or accessibility issues on Windows.

4. Remote rendering and previews

Avalonia's remote protocol (external/Avalonia/src/Avalonia.Remote.Protocol) powers the XAML previewer and custom remoting scenarios.

Potential use cases:

Security note: remote transports expose the UI tree—protect endpoints if you ship this beyond trusted tooling.

5. Tray icons, dialogs, and platform services

IWindowingPlatform.CreateTrayIcon() supplies backend-specific tray icon implementations. Use PlatformManager.CreateTrayIcon() to instantiate one:

var trayIcon = PlatformManager.CreateTrayIcon();
trayIcon.Icon = new WindowIcon("avares://Assets/tray.ico");
trayIcon.ToolTipText = "My App";
trayIcon.Menu = new NativeMenu
{
    Items =
    {
        new NativeMenuItem("Show", (sender, args) => mainWindow.Show()),
        new NativeMenuItem("Exit", (sender, args) => app.Shutdown())
    }
};
trayIcon.IsVisible = true;

Other services:

6. Browser, Android, iOS views

7. Offscreen rendering and interoperability

OffscreenTopLevel (external/Avalonia/src/Avalonia.Controls/Embedding/Offscreen/OffscreenTopLevel.cs) allows rendering to a framebuffer without showing a window—useful for:

Pair with RenderTargetBitmap to save results.

8. Practice lab: hybrid UI playbook

  1. Embed native control – Host a Win32 WebView or platform-specific map view inside Avalonia using NativeControlHost. Ensure resize and DPI updates work.
  2. Avalonia-in-native – Create a WinForms or WPF shell embedding EmbeddableControlRoot. Swap Avalonia content dynamically and synchronize focus/keyboard.
  3. Tray integration – Add a tray icon that controls window visibility and displays context menus. Test on Windows and Linux (AppIndicator fallback).
  4. Remote preview – Spin up RemoteServer with a TCP transport and connect using the Avalonia preview client to render a view remotely.
  5. Offscreen rendering – Render a control to bitmap using OffscreenTopLevel + RenderTargetBitmap and compare results in a unit test.

Document interop boundaries (threading, disposal, event forwarding) for your team.

Troubleshooting & best practices

Look under the hood (source bookmarks)

Check yourself

What's next