CSXAML

CSXAML is an experimental source-generated language for building WinUI apps with XAML-like markup and real C# expressions.

The repo and public release artifacts are licensed under Apache-2.0.

Current Status

The compiler/runtime path is broad enough for a credible v1 slice, and the remaining work is mostly release validation, public hosting, and polish around distribution.

Current productization state:

• public package boundary: Csxaml and Csxaml.Runtime
• consolidated sample apps and template work exist in the repo
• experimental post-v1 feature work exists for deeper WinUI interop and generated app roots
• benchmark and performance documentation exist for Milestone 14
• VS Code and Visual Studio extension packaging paths exist
• XML API documentation is enabled on developer-facing assemblies
• DocFX site source exists and generates API reference from XML docs at build time
• GitHub Actions owns CI, packaging, release prep, publish, and docs-site deployment workflows

Repo At A Glance

The repo is organized around four main layers:

• compiler and metadata: Csxaml.ControlMetadata, Csxaml.ControlMetadata.Generator, Csxaml.Generator
• runtime: Csxaml.Runtime, Csxaml.Testing
• performance and measurement: Csxaml.Benchmarks
• tooling and editor integration: Csxaml.Tooling.Core, Csxaml.LanguageServer, Csxaml.VisualStudio, VSCodeExtension/
• samples and build fixtures: samples/Csxaml.ExistingWinUI, samples/Csxaml.HelloWorld, samples/Csxaml.TodoApp, samples/Csxaml.FeatureGallery, samples/Csxaml.ProjectSystem.Components, samples/Csxaml.ProjectSystem.Consumer, Csxaml.ExternalControls

Project Guide

Core language and runtime

• Csxaml.ControlMetadata
  Shared metadata model for controls, properties, events, child-content rules, and value-kind hints.

• Csxaml.ControlMetadata.Generator
  Generates that metadata from WinUI and supported external controls.

• Csxaml.Generator
  Parses .csxaml, validates it, and emits deterministic generated C#.

• Csxaml.Runtime
  Retained-mode runtime that reconciles logical trees and projects them to WinUI.

• Csxaml.Testing
  Hostless component test support helpers.

• Csxaml.Benchmarks
  BenchmarkDotNet and WinUI smoke harnesses for generator, metadata, runtime, tooling, and projection measurements.

Tooling and editor integration

• Csxaml.Tooling.Core
  Shared language-service logic: completion, definitions, formatting, hover, semantic tokens, markup scanning, C# projection, and diagnostics.

• Csxaml.LanguageServer
  LSP host built on top of Csxaml.Tooling.Core.

• Csxaml.VisualStudio
  Visual Studio extension host and VSIX packaging.

• VSCodeExtension/
  VS Code extension assets, snippets, grammar, and extension host code.

Samples and fixture apps

• samples/Csxaml.ExistingWinUI Existing WinUI shell sample that mounts CSXAML through CsxamlHost.

• samples/Csxaml.HelloWorld Minimal generated-app sample that starts from App.csxaml.

• samples/Csxaml.TodoApp Advanced generated-app Todo sample showing state, DI, child components, external controls, and generated app resources without source XAML shell files.

• samples/Csxaml.FeatureGallery Generated-app feature gallery for the experimental post-v1 surface: named slots, refs, typed events, property content, expanded attached properties, resources guidance, virtualization guidance, app-hosted code presentation, and WinUI Fluent resources, controls, and hover surfaces.

• Csxaml.ExternalControls Sample external controls used to prove external-control interop.

• samples/Csxaml.ProjectSystem.Components Fixture component library for project-reference validation.

• samples/Csxaml.ProjectSystem.Consumer Generated-app fixture consumer that references the generated component library and verifies generated app/window/page roots through a normal project reference build.

Test projects

• Csxaml.ControlMetadata.Generator.Tests
• Csxaml.Generator.Tests
• Csxaml.Runtime.Tests
• Csxaml.Tooling.Core.Tests
• Csxaml.VisualStudio.Tests
• Csxaml.ProjectSystem.Tests

These projects provide regression coverage for metadata generation, parsing, validation, emission, runtime behavior, tooling, editor hosts, and project-system integration.

Non-Project Folders

• build/ - shared MSBuild targets and generation wiring
• docs/ - supporting documentation
• docs-site/ - DocFX documentation site source
• scripts/ - helper scripts
• samples/ - launchable samples, package examples, and project-system fixtures
• templates/ - template package sources
• artifacts/ - build outputs and packaged artifacts

Where To Start

If you are new to the repo, this reading order works well:

1. LANGUAGE-SPEC.md
2. docs-site/index.md
3. Csxaml.Generator/
4. Csxaml.Runtime/
5. samples/Csxaml.TodoApp/
6. Csxaml.Tooling.Core/

Key Docs

• Documentation Site Source
• Language Specification
• Roadmap
• Package Installation
• Native Props And Events
• Resources And Templates
• Performance And Scale
• Release And Versioning
• Component Testing
• Agent Working Rules And Project Inventory
• VS Code Extension

Documentation Site

The DocFX documentation site lives under docs-site/ and generates API reference pages from XML documentation comments at build time. The full docs script also requires Node.js 20.18.1 or newer with npm on PATH for CSXAML code-fence highlighting.

Build it locally from the repo root:

powershell -ExecutionPolicy Bypass -File .\scripts\docs\Invoke-DocsBuild.ps1

Preview it locally:

powershell -ExecutionPolicy Bypass -File .\scripts\docs\Invoke-DocsBuild.ps1 -Serve

Generated API YAML is written under obj\docfx\api, and the static site is written under _site.

Install Story

For outside consumers, the intended package install path is:

• install Csxaml
• keep Microsoft.WindowsAppSDK in the app project
• author .csxaml files normally

The package install guide lives in docs/package-installation.md.

For a small outside-consumer example that uses the package path instead of repo-local project references, see samples/PackageHello.

Release Model

CSXAML treats release governance as part of the product surface:

• semantic versioning is the public version contract
• Conventional Commits are the semantic input to release notes and version bumps
• git-cliff generates CHANGELOG.md and release notes
• GitHub Actions is the system of record for CI, packaging, docs, and publishing
• pushes to develop create preview releases, and pushes to master create stable releases
• release tags are created by automation after publish succeeds

The current release and versioning policy lives in docs/release-and-versioning.md.

Current Limitations

These areas remain intentionally outside the current v1 promise:

• named slots and slot fallback content
• broader external attached-property owner discovery
• open-ended event-argument projection beyond the documented experimental typed event set
• component refs and x:Name symbolic lookup; use experimental native ElementRef<T> plus Ref={...} when an imperative handle is needed
• stable-v1 generated Application, Window, Page, and ResourceDictionary roots
• stable-v1 generated app mode without source App.xaml, App.xaml.cs, MainWindow.xaml, or MainWindow.xaml.cs
• CSXAML-authored DataTemplate, ControlTemplate, StaticResource, and ThemeResource semantics; keep deep resource/template work in XAML dictionaries
• first-class CSXAML virtualization abstractions; use the performance guide and native virtualized controls for very large visible-list strategies
• DataContext-heavy third-party control interop
• dedicated source-level lifecycle or cancellation syntax

The supported feature matrix lives in docs/supported-feature-matrix.md.