Index the gallery's sample pages so other tools can consume them

[Jaylyn Barbee (Jaylyn-Barbee)]

Makes the gallery's samples readable by other tools, by publishing an index of every page and the samples on it as a single generated JSON file.

Why

The gallery is where WinUI's sample code actually lives, and it's the answer to "show me how to use this control." But that answer is only reachable by a human browsing the app, or by a program scraping this repo's markup. Scrapers are the norm today — winapp find-ui ships one — and they break every time a page moves, a sample is renamed, or an example changes shape. The gallery has no way to know it broke them, and they have no way to know they're now showing stale or partial code.

Nothing here is a new sample. The samples are already written, already reviewed, and already correct; they're just not addressable. This makes the set the gallery already maintains available as data, so the gallery stays the single source of truth for WinUI sample code instead of being the thing everyone re-derives.

What this adds

catalog/windows-samples.json, generated from the same .xaml pages and snippet bundles that the app itself renders. 123 pages, 333 samples — 290 with XAML, 127 with C#.

Each entry carries what a consumer needs to present a sample without knowing anything about this repo's layout: the control's name and description, its docs links, its keywords, and the samples themselves with their headers and code.

{
  "id": "geometry",
  "name": "Geometry",
  "description": "Clear geometric design ensures visual coherence and structure.",
  "curatedKeywords": ["path", "vector", "figures"],
  "docs": [
    { "title": "Geometry in Windows 11", "uri": "https://learn.microsoft.com/windows/apps/design/signature-experiences/geometry" }
  ],
  "samples": [
    {
      "header": "Geometry",
      "xaml": "<Grid CornerRadius=\"{StaticResource OverlayCornerRadius}\"/>\n<Grid CornerRadius=\"{StaticResource ControlCornerRadius}\"/>"
    }
  ]
}

It's a shared format, not a gallery-specific one

The file conforms to winui-sample-index.schema.json, an index contract that's already published and already consumed for other sample sources. Emitting that shape rather than inventing one means consumers need no gallery-specific adapter, and the same shape can describe a controls index or another sample source later. $schema points at the published contract so there's one source of truth and no copy to drift.

Fields that only make sense for this repo — the page path, the snippet file, the gallery group — are grouped under a gallery object on each control and sample, so what's contract and what's ours is obvious at a glance.

What makes it dependable

An index nobody can trust is worse than no index, so the generator is built around the ways this could quietly go wrong:

It can't drift from the samples. The file is generated, and the PR validation pipeline runs a step (Verify catalog/windows-samples.json is up to date) that regenerates it from the current sources and fails the build if the committed copy differs by so much as a byte. A new sample can't land without the index following. It isn't auto-committed — the failure tells you to run dotnet run --project tools/CatalogExporter -- generate and commit the result, so the index stays a reviewable part of the diff rather than something a bot rewrites underneath you.

Sample order is stable. Consumers address samples positionally, so samples are emitted in page order — the order a reader sees them in the app. Appending is safe. Alphabetical-by-filename order was the earlier approach and is subtly wrong: adding ButtonA.txt would renumber every later sample on that page and silently repoint existing references at different code.

Nothing is published that a consumer will silently discard. Consumers drop samples whose XAML doesn't parse, which is the worst failure mode because it looks like success on our side. The generator runs the same well-formedness check the consumer does and reports what it withheld.

That withholds 12 snippets, all deliberate authored elisions like <Window ...> — right for the gallery's code viewer, impossible as XML. All 12 still publish their C#, so no sample is lost.

A second check withholds 7 more: fragments that bind an XML namespace prefix their page never declares. These parse fine in isolation, which is why they went unnoticed, and fail only when a reader pastes them alongside the imports we publish. That is strictly worse than malformed XAML, because it clears our gate and breaks at their end instead of ours. Five still publish their C#; two are XAML-only and so leave the index entirely (FlipviewShowingBoundData, LayingOutNestedItemsrepeaters). Both bind gallery-internal types through x:DataType, so no import would have rescued them — they were never portable, and withholding them is the honest result.

One further XAML-only snippet is dropped outright (OtherXamlEasingFunctions, which uses a token as an element name resolved from code-behind). All 20 are pinned by a test so the set can't grow unnoticed.

Code is published as a reader would see it. Snippets contain $(Token) placeholders bound to each page's interactive options; published verbatim, many are not valid XAML. They now resolve to the value the control starts with — what the gallery shows on load. Resolution reads only what the markup states; when the answer depends on running code, the XAML attribute carrying the token is deleted so the property falls back to its own default, and a gate asserts none survives. Publishing a value the gallery never shows would be worse than publishing none. C# is the exception and is covered below.

What maintainers are taking on

Two new top-level folders and one generated data file. Nothing existing is restructured, and the gallery app itself gains no new runtime dependency — the exporter is a build-time console tool that never ships inside the app.

Path	What it is
catalog/windows-samples.json	The generated index (10,642 lines, 684 KB). Output, not source — never hand-edit it; run generate and commit the result.
catalog/README.md	Explains the format, what each field means, and how to regenerate. Start here.
tools/CatalogExporter/Program.cs	Entry point. Two commands: generate writes the index, check fails if the committed copy is stale.
tools/CatalogExporter/CatalogGenerator.cs	The bulk of the logic (670 lines): reads ControlInfoData.json and the sample pages, builds the index.
tools/CatalogExporter/CatalogModels.cs	The output shape. Property declaration order is the JSON field order.
tools/CatalogExporter/SourceModels.cs	Typed view of ControlInfoData.json.
tools/CatalogExporter/SampleBundle.cs	Parses .txt snippet bundles. Deliberately mirrors ControlExample.ParseSampleCodeSections.
tools/CatalogExporter/SubstitutionResolver.cs	Resolves $(Token) placeholders to the value each page's control starts with.
tools/CatalogExporter/TokenFallback.cs	Removes the attribute carrying a token the resolver could not settle, and records its name. Holds the gate that asserts no token reaches published XAML.
tools/CatalogExporter/XamlFragment.cs	The well-formedness gate and namespace-prefix detection.
tests/WinUIGallery.CatalogExporter.Tests/	73 tests across 6 files. Includes the staleness guard and the pinned list of snippets whose XAML can't be published.
14 new .txt bundles under Samples/AccessibilityKeyboard/ and Samples/AccessibilityScreenReader/	Sample code migrated out of inline page markup. Same code, same rendering — just reachable by tooling now.

Six existing files are modified, all narrowly:

Path	Change
WinUIGallery.slnx	Adds the two new projects.
.pipelines/azure-pipelines.yml	Adds the staleness-check step described below.
ControlInfoData.json	Adds an optional Catalog block to two entries (search aliases only), and drops two dangling RelatedControls references from LayoutPanel.
ControlInfoDataSchema.json	Documents that optional Catalog block: Exclude, Aliases, RelatedSamples.
AccessibilityKeyboardPage.xaml, AccessibilityScreenReaderPage.xaml	Inline sample code replaced with SampleDefinition references to the new bundles.

The Catalog block in ControlInfoData.json is opt-in and additive. The running gallery app never reads it, and omitting it is the normal case — it exists only for the rare sample that needs to override what the exporter would otherwise derive on its own.

What runs in CI, and when

One step is added to the existing WinUI-Gallery-PRValidation pipeline, so it runs on every PR and on pushes to main alongside the checks already there. No new pipeline, no new schedule, no new secrets, and nothing that publishes anywhere.

Step	When	What it does	How it fails
Verify catalog/windows-samples.json is up to date	Every PR build, before the app build	Runs the 73 exporter tests. The key one regenerates the index from the current sample sources and byte-compares it to the committed file.	Build fails with the exact command to fix it: dotnet run --project tools/CatalogExporter -- generate, then commit.

It adds roughly 7 seconds of test time plus the exporter's own build. It never writes to the repo — no bot commits, no auto-push. A stale index is surfaced as a failing check and fixed by the contributor, so the generated file stays visible in review instead of changing underneath you.

One thing worth knowing: the guard is a test, and it throws if it can't locate the repo root rather than skipping. It can't silently pass in an environment where it didn't really run.

Incidental fixes found along the way

Some samples supplied their code as inline <ControlExample.Xaml> markup instead of a snippet bundle. They rendered fine in the app but were invisible to any export, with no symptom. They're migrated to bundles, and a test fails if the inline form comes back.

ControlInfoDataSchema.json does not parse as strict JSON on main: there's a dangling comma before a closing brace (line 101). PowerShell's ConvertFrom-Json tolerates it, JSON.parse does not, and nothing in CI parses this file strictly, which is how it drifted unnoticed. It parses now — though worth flagging that the fix is positional rather than deliberate: the new optional Catalog property happens to land exactly where the dangling comma was, so the comma now separates two real properties. Validating this file in CI would be a reasonable small follow-up.

Verification

Beyond the exporter's 73 tests:

• Validated against the published contract with ajv (draft 2020-12).
• Every published XAML fragment clears the same well-formedness check a consumer applies, and a build-time gate fails the export outright if a $(Token) reaches published XAML. Both run on every PR rather than being spot-checked, so a consumer discards nothing: 290 XAML and 127 code blocks publish, none of the XAML carrying a placeholder.
• The gallery app builds clean, and every SampleDefinition reference resolves — a dangling one compiles fine and shows an empty code viewer at runtime. The exporter validates the full Folder\File.txt path rather than just the file name, matching how ControlExample resolves it at runtime.

Notes for reviewers

• The exporter began as Niels Laute (@niels9001)'s work in Export WinUI Gallery samples as a catalog/windows-samples.json manifest #2226, preserved here as the first commit; this supersedes that PR.
• SampleBundleParser deliberately mirrors ControlExample.ParseSampleCodeSections. If the two drift, the index publishes code users never actually see, so the tests pin the rules most likely to be got wrong.
• A prefix a page doesn't declare — a snippet using local: to mean "your namespace" — was originally omitted from xmlnsImports rather than guessed at, since an invented URI would look authoritative and not compile. That still left the fragment published but unusable, so the fragment itself is now withheld and the offending prefixes recorded in gallery.xamlOmittedUnboundPrefixes.
• 7 pages emit zero samples because every example on them is code-less or withheld. That's legal and visible in the output rather than hidden.

$(Token) placeholders

Snippets carry $(Token) placeholders that the gallery substitutes at runtime from live control values. Published verbatim they break the contract's promise of code "exactly as it should be pasted into a project".

Published XAML now contains none. The exporter resolves a token from what the markup states; where it can't, it deletes the attribute carrying it, so the property falls back to its own default. A build-time gate then fails the export if any token survives in published XAML, so the guarantee is asserted rather than assumed. 0 tokens across 290 XAML samples, with 40 samples listing what was removed in gallery.xamlPlaceholdersDropped so the omission is inspectable rather than invisible.

The tradeoff is deliberate. A dropped attribute can leave a sample not matching the gallery's rendering 1:1, but it always compiles. Inference was tried and rejected: 13 sliders declare Minimum > 0, so a guessed Value silently coerces to something the gallery never shows, and several pages set real values in their constructors. Not resolving beats resolving badly.

This adds no work for anyone writing a sample. A new token nobody has taught the exporter about degrades to a dropped attribute on its own.

C# still carries 11, across 6 controls. The XAML approach has no C# equivalent, because no C# construct yields a default by being absent. The tokens appear as identifier fragments (BadgeNotificationGlyph.$(SelectedGlyph)), fixed-arity arguments (SetBorderAndTitleBar($(HasBorder), $(HasTitleBar))), and entire statements, none of which can be deleted without a syntax error or gutting the sample. Those samples publish their code as-is.

They are now declared rather than resolved. gallery.codePlaceholdersPresent lists the token names on each of those 11 samples, so a consumer knows up front that the C# is not pasteable instead of finding out at compile time.

It is deliberately not symmetric with xamlPlaceholdersDropped. That field means "removed, output is clean"; this one means "still present, output is not." A consumer conflating the two would paste non-compiling C#, which is the exact failure the field exists to prevent, so the names differ and catalog/README.md states the asymmetry explicitly. No fatal gate is added for C#, because unlike XAML these tokens are expected and allowed.

What contributors need to know once this lands

Two things will surprise someone otherwise, and both are cheap to say up front.

Adding a sample gains a second step. Deriving the index is automatic: a new Samples/{UniqueId}/ folder is picked up with no registration, no list to append to, and no mapping table. Regenerating it is not. Any PR that adds, renames, or removes a sample, or edits a snippet .txt, has to run dotnet run --project tools/CatalogExporter -- generate and commit the result, or the staleness check fails. The failure lands on a PR whose diff may look entirely unrelated to catalog/, which is the part that reads as a mystery if you haven't hit it before. The error message names the exact command to fix it.

This branch is its own worked example. #2233 and #2234 merged while it was open, and their three new controls and eight new samples flowed into the index the moment the generator was next run — including #2234's consolidation of two Windowing snippets into one, which the index tracked as a rename with no manual intervention and no mapping to maintain.

RelatedControls gains its first consumer, and its schema description is misleading. ControlInfoDataSchema.json documents the field as "UniqueIds of other controls" — accurate, and obeyed by 330 of the 332 references currently on main. It then says those values are "used to surface 'Related controls' suggestions on the control's detail page," and no such code exists: the field has no .cs or .xaml reader anywhere in WinUIGallery/. Until now a wrong value did nothing observable, so nothing caught one — and an author reading that sentence would reasonably expect a mistake to show up by running the app.

The exporter is the first thing to read the field, and it validates the cross-references so a dangling entry is a build failure rather than a silent dead link. LayoutPanel arrived from #2233 listing Panel and StackLayout, which are WinUI type names rather than gallery pages; both are dropped here, leaving ItemsRepeater. Nothing is lost, since Panel was already published through BaseClasses and Tags. Correcting that stale second sentence in the schema is a reasonable follow-up, as it is the part that would mislead the next author.

Follow-up, deliberately not in this PR

WinUIGallery/Samples/SampleCode/ is a leftover from an older layout. Of its 164 .txt files, 157 (~181 KB) are reachable by nothing — no SampleDefinition, no CodeSourceFile, no code-behind path — yet WinUIGallery.csproj globs Samples\**\*.txt, so all of them ship inside the app as dead payload.

The folder can't be deleted wholesale: 7 files are still loaded by name from code-behind, 3 under ScrollView\ (ScrollViewPage.xaml.cs) and 4 under Templates\ (TemplatesPage.xaml.cs). Those paths are built as runtime strings, so no build-time check catches them — worth knowing for whoever picks up the cleanup.

[Jaylyn Barbee (Jaylyn-Barbee)]

Niels Laute (@niels9001) — picking this up from #2226 with your blessing; your exporter commit is preserved as the first commit here, and this supersedes that PR.

Since your draft, the main change is that the index now targets a shared, versioned contract rather than a gallery-shaped format, so winapp (and anything else) can consume it without scraping the repo. I then reviewed the emitted JSON field-by-field against that contract and fixed three places where what we published didn't match what the contract promises:

• usings was never emitted. 51 controls ship C# and none carried it, so BreadcrumbBar published ObservableCollection<Folder> with nothing to resolve it. Now taken from each page's code-behind imports, with the gallery's own namespaces filtered out.
• relatedControls shipped UniqueIds instead of display names. Binding listed XamlResources and XamlStyles; it now reads Resources and Style. 29 of 322 entries were affected.
• Namespace detection missed prefixed types inside prefixed attributes. x:DataType="local:Contact" found only x, so 13 samples published XAML with an undeclared prefix.

There's one thing I'd rather not decide alone, and it's in the description under One open question: the 49 samples that still carry an unresolved $(Token). The exporter resolves what it can statically, but things like $(SelectedAppNotificationSoundEvent) bind to controls populated in code-behind, so there's no static answer. Publishing as-is is still better than today's scraping, which resolves nothing — but it doesn't match the contract's "exactly as it should be pasted" wording, and dropping the affected fields would delete 41 samples outright. You know the substitution system far better than I do, so I'd value your read.

Everything else is verified rather than asserted: 51 exporter tests pass, the index validates against the published schema with ajv, the gallery app builds clean, and CI regenerates and byte-compares the index on every PR so it can't silently drift.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

🟡 Changes recommended

The exporter currently publishes non-pasteable samples and can validate paths the gallery cannot load.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

tools/CatalogExporter/CatalogGenerator.cs:533

• The shared contract defines code as C# that can be pasted directly, but this branch deliberately publishes unresolved placeholders. The committed catalog already contains values such as AppNotificationSoundEvent.$(SelectedAppNotificationSoundEvent), and the current winappCli parser has no support for gallery.codePlaceholdersPresent, so these brace-balanced snippets survive sanitization and are presented as broken C#. Please either resolve/omit templated code or add consumer-supported placeholder semantics to the shared contract before publishing it.

• Files reviewed: 39/40 changed files
• Comments generated: 3
• Review effort level: Balanced

[Copilot]

🟢 Approval recommended

The exporter is comprehensively validated, prior findings are resolved, and no remaining correctness issues were identified.

Review details

• Files reviewed: 40/41 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Niels Laute (niels9001)]

/azp run