1. Home
  2. Docs
  3. Getting Started
  4. Installation

Installation

AXSG ships multiple install surfaces because different users need different entry points.

Choose the right artifact

Application author

Use the umbrella package when you want the normal app-facing install path:

<PackageReference Include="XamlToCSharpGenerator" Version="x.y.z" />

This is the recommended starting point for Avalonia applications.

For Avalonia apps, the package reference alone is not the whole setup. AXSG keeps backend selection explicit, so you also need to:

  1. opt the project into the SourceGen backend
  2. enable the AXSG runtime bootstrap on AppBuilder

Minimal project setup:

<ItemGroup>
  <PackageReference Include="XamlToCSharpGenerator" Version="x.y.z" />
</ItemGroup>

<PropertyGroup>
  <AvaloniaXamlCompilerBackend>SourceGen</AvaloniaXamlCompilerBackend>
</PropertyGroup>

Minimal runtime bootstrap:

using XamlToCSharpGenerator.Runtime;

public static AppBuilder BuildAvaloniaApp() =>
    AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .UseAvaloniaSourceGeneratedXaml();

Build/package integrator

If you need explicit control over the imported build layer, start from:

<PackageReference Include="XamlToCSharpGenerator.Build" Version="x.y.z" />

Editor/tooling integration

Use the .NET tool when you need the standalone language server:

dotnet tool install --global XamlToCSharpGenerator.LanguageServer.Tool --version x.y.z

Use the VS Code extension when you want the bundled editor experience instead of wiring the tool manually.

Minimum project expectations

For the main Avalonia path, a project should have:

  • the AXSG package reference
  • AvaloniaXamlCompilerBackend=SourceGen
  • an Avalonia application/runtime setup
  • .UseAvaloniaSourceGeneratedXaml() in the app bootstrap path
  • x:DataType on binding scopes where compiled binding semantics are required
  • build enabled so generated files can be produced on the first pass

Class-backed XAML code-behind

If the project already contains hand-written InitializeComponent() methods that call AvaloniaXamlLoader.Load(this), do not leave those methods unconditional when you switch to AXSG.

AXSG generates InitializeComponent(bool loadXaml = true) for class-backed XAML, and normal constructor calls such as InitializeComponent(); are expected to bind to that generated method. A hand-written parameterless overload wins overload resolution and will bypass AXSG output.

Use one of these patterns:

  • sourcegen-only project: remove the manual AvaloniaXamlLoader.Load(this) method
  • mixed-backend or multi-target project: keep it behind #if !AXAML_SOURCEGEN_BACKEND

Recommended portable pattern:

public MainWindow()
{
    InitializeComponent();
}

#if !AXAML_SOURCEGEN_BACKEND
private void InitializeComponent()
{
    global::Avalonia.Markup.Xaml.AvaloniaXamlLoader.Load(this);
}
#endif

Use the dedicated article for the full explanation of why this works and how it interacts with generated partials:

After installing:

  1. Build once so generated artifacts and diagnostics are available.
  2. Confirm the app uses .UseAvaloniaSourceGeneratedXaml() before debugging runtime loading or hot reload.
  3. Confirm class-backed views do not keep an unconditional parameterless InitializeComponent() wrapper around AvaloniaXamlLoader.Load(this).
  4. Add or verify x:DataType on key views, templates, and themes.
  5. Open the sample catalog if you want a feature-by-feature reference implementation.