Skip to main content
The AppBuilder class provides a fluent API for configuring platform-specific services before starting an Avalonia application. It handles initialization of windowing subsystems, rendering engines, text shaping, and runtime platform services.

​
Overview

The AppBuilder is used to:
  • Configure the application instance
  • Set up windowing subsystems (Win32, X11, Cocoa, etc.)
  • Configure rendering backends (Skia, Direct2D, etc.)
  • Set up text shaping (HarfBuzz)
  • Register platform-specific options
  • Initialize the application with proper lifecycle

​
Namespace

Avalonia

​
Properties

​
Instance
Application?
Gets the Application instance being initialized. This is null until Setup() is called.
​
ApplicationType
Type?
Gets the type of the application instance (even if it hasn’t been created yet).
​
WindowingSubsystemName
string?
Gets the name of the currently selected windowing subsystem (e.g., “Win32”, “X11”, “Cocoa”).
​
RenderingSubsystemName
string?
Gets the name of the currently selected rendering subsystem (e.g., “Skia”).
​
TextShapingSubsystemName
string?
Gets the name of the currently selected text shaping subsystem (e.g., “HarfBuzz”).
​
RuntimePlatformServicesName
string?
Gets the name of the currently selected runtime platform subsystem.

​
Methods

​
Configure

public static AppBuilder Configure<TApp>() where TApp : Application, new()
Begins configuring an Avalonia application with the specified application type. Type Parameters:
​
TApp
Application
required
The subclass of Application to configure. Must have a parameterless constructor.
Returns: An AppBuilder instance for further configuration. Example: 
AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .StartWithClassicDesktopLifetime(args);

public static AppBuilder Configure<TApp>(Func<TApp> appFactory) where TApp : Application
Begins configuring an Avalonia application with a factory function. Useful for dependency injection.
​
appFactory
Func<TApp>
required
Factory function that creates the application instance.
Example: 
AppBuilder.Configure(() => new App(serviceProvider))
    .UsePlatformDetect()
    .StartWithClassicDesktopLifetime(args);

​
UseWindowingSubsystem

public AppBuilder UseWindowingSubsystem(Action initializer, string name = "")
Specifies a windowing subsystem to use.
​
initializer
Action
required
The method to call to initialize the windowing subsystem.
​
name
string
The name of the windowing subsystem for identification.
Returns: The AppBuilder instance for method chaining. Example: 
builder.UseWindowingSubsystem(() => Win32Platform.Initialize(), "Win32");

​
UseRenderingSubsystem

public AppBuilder UseRenderingSubsystem(Action initializer, string name = "")
Specifies a rendering subsystem to use.
​
initializer
Action
required
The method to call to initialize the rendering subsystem.
​
name
string
The name of the rendering subsystem.
Returns: The AppBuilder instance for method chaining.

​
UseTextShapingSubsystem

public AppBuilder UseTextShapingSubsystem(Action initializer, string name = "")
Specifies a text shaping subsystem to use (typically HarfBuzz).
​
initializer
Action
required
The method to call to initialize the text shaping subsystem.
​
name
string
The name of the text shaping subsystem.
Returns: The AppBuilder instance for method chaining.

​
UseRuntimePlatformSubsystem

public AppBuilder UseRuntimePlatformSubsystem(Action initializer, string name = "")
Specifies a runtime platform subsystem to use (handles asset loading, etc.).
​
initializer
Action
required
The method to call to initialize the runtime platform subsystem.
​
name
string
The name of the runtime platform subsystem.
Returns: The AppBuilder instance for method chaining.

​
UseStandardRuntimePlatformSubsystem

public AppBuilder UseStandardRuntimePlatformSubsystem()
Configures the standard runtime platform subsystem, which provides default asset loading and platform services. Returns: The AppBuilder instance for method chaining.

​
With

public AppBuilder With<T>(T options)
Configures platform-specific options by binding them to the service locator.
​
options
T
required
The options instance to register.
Example: 
builder.With(new Win32PlatformOptions
{
    UseWgl = false,
    AllowEglInitialization = true
});

public AppBuilder With<T>(Func<T> options)
Configures platform-specific options using a factory function.
​
options
Func<T>
required
Factory function that creates the options instance.

​
WithDataAnnotationsValidation

public AppBuilder WithDataAnnotationsValidation()
Adds support for data validation using System.ComponentModel.DataAnnotations. Returns: The AppBuilder instance for method chaining. Example: 
AppBuilder.Configure<App>()
    .WithDataAnnotationsValidation()
    .UsePlatformDetect();

​
ConfigureFonts

public AppBuilder ConfigureFonts(Action<FontManager> action)
Registers an action that is executed with the current font manager, allowing custom font configuration.
​
action
Action<FontManager>
required
The action to execute with the font manager.
Example: 
builder.ConfigureFonts(manager =>
{
    manager.AddFontCollection(new EmbeddedFontCollection(
        new Uri("fonts:MyApp", UriKind.Absolute),
        new Uri("avares://MyApp/Assets/Fonts", UriKind.Absolute)));
});

​
AfterSetup

public AppBuilder AfterSetup(Action<AppBuilder> callback)
Registers a callback to be executed after the application setup is complete.
​
callback
Action<AppBuilder>
required
The callback to execute after setup.
Returns: The AppBuilder instance for method chaining.

​
AfterPlatformServicesSetup

public AppBuilder AfterPlatformServicesSetup(Action<AppBuilder> callback)
Registers a callback to be executed after platform services are set up but before the application is created.
​
callback
Action<AppBuilder>
required
The callback to execute after platform services setup.
Returns: The AppBuilder instance for method chaining.

​
SetupWithoutStarting

public AppBuilder SetupWithoutStarting()
Sets up the platform-specific services for the application but does not start it. Useful for testing or custom lifetime management. Returns: The AppBuilder instance. Example: 
var builder = AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .SetupWithoutStarting();

var app = builder.Instance;

​
SetupWithLifetime

public AppBuilder SetupWithLifetime(IApplicationLifetime lifetime)
Sets up the platform-specific services and initializes the application with a particular lifetime, but does not run it.
​
lifetime
IApplicationLifetime
required
The application lifetime to use.
Returns: The AppBuilder instance.

​
Start

public void Start(AppMainDelegate main, string[] args)
Sets up the application and runs a custom main delegate.
​
main
AppMainDelegate
required
The delegate to execute with the application instance and arguments.
​
args
string[]
required
Command-line arguments to pass to the delegate.
Delegate signature: 
public delegate void AppMainDelegate(Application app, string[] args);

​
Usage Example

Here’s a complete example of configuring and starting an Avalonia application: 
using Avalonia;
using Avalonia.Controls.ApplicationLifetimes;

class Program
{
    public static void Main(string[] args)
    {
        BuildAvaloniaApp()
            .StartWithClassicDesktopLifetime(args);
    }

    public static AppBuilder BuildAvaloniaApp()
        => AppBuilder.Configure<App>()
            .UsePlatformDetect()
            .WithInterFont()
            .LogToTrace();
}

​
Platform-Specific Configuration

​
Windows

AppBuilder.Configure<App>()
    .UseWin32()
    .UseSkia()
    .StartWithClassicDesktopLifetime(args);

​
macOS

AppBuilder.Configure<App>()
    .UseMacOS()
    .UseSkia()
    .StartWithClassicDesktopLifetime(args);

​
Linux

AppBuilder.Configure<App>()
    .UseX11()
    .UseSkia()
    .StartWithClassicDesktopLifetime(args);

​
Cross-Platform (Automatic Detection)

AppBuilder.Configure<App>()
    .UsePlatformDetect() // Automatically detects and configures for the current platform
    .StartWithClassicDesktopLifetime(args);

​
Advanced Configuration

​
Custom Font Configuration

AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .ConfigureFonts(manager =>
    {
        manager.AddFontCollection(new EmbeddedFontCollection(
            new Uri("fonts:MyApp", UriKind.Absolute),
            new Uri("avares://MyApp/Assets/Fonts", UriKind.Absolute)));
    })
    .StartWithClassicDesktopLifetime(args);

​
Data Annotations Validation

AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .WithDataAnnotationsValidation()
    .StartWithClassicDesktopLifetime(args);

​
Dependency Injection

var services = new ServiceCollection();
// Configure services...
var serviceProvider = services.BuildServiceProvider();

AppBuilder.Configure(() => new App(serviceProvider))
    .UsePlatformDetect()
    .StartWithClassicDesktopLifetime(args);

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us