name

avalonia-xaml-source-generator

description

Comprehensive guide for choosing, installing, wiring, and troubleshooting XamlToCSharpGenerator (AXSG) packages in Avalonia projects. Use when Codex needs to add AXSG to an Avalonia app, select among the public AXSG packages or tooling artifacts, configure SourceGen MSBuild switches, set up runtime or hot reload support, embed AXSG editor/language-service tooling, or compose lower-level compiler/runtime packages in this repository.

Avalonia Xaml Source Generator

Choose the smallest public AXSG artifact set that satisfies the task, then wire the matching MSBuild and runtime pieces. Prefer app-facing packages first and drop to low-level compiler/runtime packages only when the request is explicitly about custom composition, framework work, or tooling internals.

Workflow

Classify the request before recommending packages.

Standard Avalonia app: start with references/package-surface.md and references/avalonia-app-setup.md.
Hot reload, hot design, runtime fallback, or loader issues: read references/avalonia-app-setup.md and references/configuration-switches.md.
VS Code, LSP, or in-app editor work: read references/tooling-and-lsp.md.
Custom compiler host, framework profile, parser reuse, or advanced package composition: read references/advanced-composition.md.

Prefer the highest-level install surface that matches the request.

Use XamlToCSharpGenerator for normal Avalonia app adoption.
Use XamlToCSharpGenerator.Build only when the user explicitly wants MSBuild-only integration or custom target layering.
Use low-level compiler/runtime/tooling packages only when the task is about embedding or extending AXSG itself.

Include the required wiring, not just the package name.

Show the package or tool install command.
Show AvaloniaXamlCompilerBackend set to SourceGen for app setup.
Show runtime bootstrap with UseAvaloniaSourceGeneratedXaml() when runtime support matters.
Mention build-side automatic behavior when relevant: SourceGen disables the legacy Avalonia XAML compilation path and the Avalonia name generator.

Guardrails

Treat the public surface in references/package-surface.md as the supported install matrix.
Do not recommend internal support projects such as XamlToCSharpGenerator.DotNetWatch.Proxy as consumer dependencies.
Do not mix default Avalonia XamlIl instructions with AXSG setup in the same recipe without calling out the backend switch explicitly.
Preserve the repository AOT/trimming contract. Do not suggest reflection-based runtime/emitted-code workarounds.
For repo-local examples, mirror the established SourceGenCrudSample project pattern instead of inventing new item names or imports.

References

references/package-surface.md: full public package, tool, and VS Code artifact inventory.
references/avalonia-app-setup.md: standard app setup, bootstrap, and repo-local development wiring.
references/tooling-and-lsp.md: language service, CLI LSP host, VS Code extension, and in-app editor guidance.
references/advanced-composition.md: compiler stack layering and low-level package combinations.
references/configuration-switches.md: canonical AXSG MSBuild switches grouped by scenario.

Avalonia Xaml Source Generator

Workflow

Classify the request before recommending packages.

Standard Avalonia app: start with references/package-surface.md and references/avalonia-app-setup.md.

Hot reload, hot design, runtime fallback, or loader issues: read references/avalonia-app-setup.md and references/configuration-switches.md.

VS Code, LSP, or in-app editor work: read references/tooling-and-lsp.md.

Custom compiler host, framework profile, parser reuse, or advanced package composition: read references/advanced-composition.md.

Prefer the highest-level install surface that matches the request.

Use XamlToCSharpGenerator for normal Avalonia app adoption.

Use XamlToCSharpGenerator.Build only when the user explicitly wants MSBuild-only integration or custom target layering.

Use low-level compiler/runtime/tooling packages only when the task is about embedding or extending AXSG itself.

Include the required wiring, not just the package name.

Show the package or tool install command.

Show AvaloniaXamlCompilerBackend set to SourceGen for app setup.

Show runtime bootstrap with UseAvaloniaSourceGeneratedXaml() when runtime support matters.

Mention build-side automatic behavior when relevant: SourceGen disables the legacy Avalonia XAML compilation path and the Avalonia name generator.

Guardrails

Treat the public surface in references/package-surface.md as the supported install matrix.

Do not recommend internal support projects such as XamlToCSharpGenerator.DotNetWatch.Proxy as consumer dependencies.

Do not mix default Avalonia XamlIl instructions with AXSG setup in the same recipe without calling out the backend switch explicitly.

Preserve the repository AOT/trimming contract. Do not suggest reflection-based runtime/emitted-code workarounds.

For repo-local examples, mirror the established SourceGenCrudSample project pattern instead of inventing new item names or imports.

References

references/package-surface.md: full public package, tool, and VS Code artifact inventory.

references/avalonia-app-setup.md: standard app setup, bootstrap, and repo-local development wiring.

references/tooling-and-lsp.md: language service, CLI LSP host, VS Code extension, and in-app editor guidance.

references/advanced-composition.md: compiler stack layering and low-level package combinations.

references/configuration-switches.md: canonical AXSG MSBuild switches grouped by scenario.