2. Set up tools and build your first project

Goal

Why this matters

Prerequisites by operating system

SDK matrix at a glance

Avalonia 11 targets .NET 8.0. The official repository pins versions in global.json:

Scenario SDK / Tooling Notes
Desktop (Windows/macOS/Linux) .NET SDK 8.0.x Use latest LTS; global.json ensures consistent builds across machines.
Android .NET SDK 8.0.x + android workload Requires Android Studio or Visual Studio mobile workloads.
iOS/macOS Catalyst .NET SDK 8.0.x + ios workload Requires Xcode CLI tools and Apple certificates for device deployment.
Browser (WebAssembly) .NET SDK 8.0.x + wasm-tools workload Installs Emscripten toolchain for WASM builds.

Run dotnet --list-sdks to confirm the expected SDK version is installed. When multiple SDKs coexist, keep a repo-level global.json to pin builds to the Avalonia-supported version.

Windows

macOS

Linux (Ubuntu/Debian example)

Verify your SDK installation:

dotnet --version
dotnet --list-sdks

Make sure the Avalonia-supported SDK (currently .NET 8.x for Avalonia 11) appears in the list before moving on.

Optional workloads for advanced targets

Run these commands only if you plan to target additional platforms soon (you can add them later):

dotnet workload install wasm-tools      # Browser (WebAssembly)
dotnet workload install android         # Android toolchain
dotnet workload install ios             # iOS/macOS Catalyst toolchain
dotnet workload install maui           # Optional: Windows tooling support

# Restore workloads declared in a solution (after cloning a repo)
dotnet workload restore

If a workload fails, run dotnet workload repair and confirm your IDE also installed the Android/iOS dependencies (Android SDK Managers, Xcode command-line tools).

Visual Studio 2022 (Windows)

JetBrains Rider

Visual Studio Code

Install Avalonia project templates

dotnet new install Avalonia.Templates

This adds templates such as avalonia.app, avalonia.mvvm, avalonia.reactiveui, and avalonia.xplat.

Verify installation:

dotnet new list avalonia

You should see a table of available Avalonia templates.

Template quick-reference

Template Command When to use
Desktop (code-behind) dotnet new avalonia.app -n MyApp Small prototypes with code-behind patterns.
MVVM starter dotnet new avalonia.mvvm -n MyApp.Mvvm Includes a ViewModel base class and sample bindings.
ReactiveUI dotnet new avalonia.reactiveui -n MyApp.ReactiveUI If you standardise on ReactiveUI for MVVM.
Cross-platform heads dotnet new avalonia.app --multiplatform -n MyApp.Multi Generates desktop, mobile, and browser heads in one project.
Split head projects dotnet new avalonia.xplat -n MyApp.Xplat Separate desktop/mobile projects (Visual Studio friendly).
Control library dotnet new avalonia.library -n MyApp.Controls Create reusable UI/control libraries.

Pair this with dotnet workload list to confirm matching workloads are installed for the heads you create.

Create and run your first project (CLI-first flow)

# Create a new solution folder
mkdir HelloAvalonia && cd HelloAvalonia

# Scaffold a desktop app template (code-behind pattern)
dotnet new avalonia.app -o HelloAvalonia.Desktop

cd HelloAvalonia.Desktop

# Restore packages and build
dotnet build

# Run the app
dotnet run

A starter window appears. Close it when done.

Alternative templates

Open the project in your IDE

Visual Studio

  1. File -> Open -> Project/Solution -> select HelloAvalonia.Desktop.csproj.
  2. Press F5 (or the green Run arrow) to launch with the debugger.
  3. Verify XAML Hot Reload by editing MainWindow.axaml while the app runs.

Rider

  1. File -> Open -> choose the solution folder.
  2. Use the top-right run configuration to run/debug.
  3. Open the Avalonia Previewer tool window to see live XAML updates.

VS Code

  1. code . inside the project directory.
  2. Accept the prompt to add build/debug assets; VS Code generates launch.json and .vscode/tasks.json.
  3. Use the Run and Debug panel (F5) and the Avalonia preview extension for live previews.

Generated project tour (why each file matters)

Make a visible change and rerun


<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        x:Class="HelloAvalonia.MainWindow"
        Width="400" Height="260"
        Title="Hello Avalonia!">
  <StackPanel Margin="16" Spacing="12">
    <TextBlock Text="It works!" FontSize="24"/>
    <Button Content="Click me" HorizontalAlignment="Left"/>
  </StackPanel>
</Window>

Rebuild and run (dotnet run or IDE Run) to confirm the change.

Troubleshooting checklist

Building from source gives you binaries with the latest commits, useful for testing fixes or contributing.

Practice and validation

  1. Confirm your environment with dotnet --list-sdks and dotnet workload list. If workloads are missing, run dotnet workload restore.
  2. Install the Avalonia templates and scaffold each template from the quick-reference table. Capture which commands require additional workloads.
  3. Run one generated app from the CLI and another from your IDE, verifying hot reload or the previewer works in both flows.
  4. Clone the Avalonia repo, build it (./build.sh --target=Build or .\build.ps1 -Target Build), and run the ControlCatalog sample.
  5. Inspect samples/ControlCatalog/ControlCatalog.csproj and map referenced Avalonia packages to their source folders. Update your architecture sketch with these relationships.
  6. Set a breakpoint in App.axaml.cs (OnFrameworkInitializationCompleted) and step through startup to watch the lifetime initialise.
  7. Document SDK versions, workloads, and template output in a team README so new developers can reproduce your setup.

Look under the hood (source bookmarks)

Check yourself

What's next