# WinUI 3 Gallery: a Microsoft sample app that doubles as its own documentation

> WinUI 3 Gallery is a C# desktop app under the MIT licence that demonstrates every WinUI 3 control and Fluent Design pattern. It pins an experimental Windows App SDK build, self-contained deploys, and carries its build troubleshooting inline in the README.

**microsoft/WinUI-Gallery** — This app demonstrates the controls available in WinUI and the Fluent Design System.

- Repository: https://github.com/microsoft/WinUI-Gallery
- Website: https://aka.ms/winui
- Stars: 3,654 · Forks: 758
- Language: C#
- License: MIT
- Published: 2026-10-08 · Updated: 2026-10-08 · Language: en
- Canonical page: https://hysenlabs.com/projects/microsoft-winui-gallery

## A companion app that has to work before it can teach

GitHub reports the repository description as a single line: this app demonstrates the controls available in WinUI and the Fluent Design System. The README expands on that into a companion app for WinUI and Windows App SDK APIs, and describes it as the interactive companion to the Fluent Design guidelines, showing usage through interactive samples, tools and code snippets.

That framing matters more than it looks. A gallery app that only compiled would not teach anything, so every sample in this repository is also a test of the build configuration described a few paragraphs later. The primary language is C#, the licence is MIT with the text at the repository root, and the declared homepage is `https://aka.ms/winui`. The topic list is unusually long for an app rather than a framework, and it reads like a set of search keywords rather than a taxonomy: `fluent`, `fluent-design`, `uwp`, `windows`, `windowsappsdk`, `winrt`, `winui`, `winui-controls`, `winui3`, `xaml`, `xaml-layout`, `xaml-style`, `xaml-theme`, `xaml-winrt`. Six of those fourteen are XAML variants, which is an accurate hint about where the density of this codebase sits.

The features section lists four things. Each control page shows the markup and codebehind used to create each example. The app includes the latest WinUI NuGet package and shows how to use controls like NavigationView and SwipeControl. It is responsive itself, demonstrating adaptive layout across form factors rather than only documenting it. And design plus accessibility pages are described as making the gallery a useful developer companion.

The repository is not archived, sits on `main`, and GitHub reports the last push on 2026-09-23. It has 3654 stars, 758 forks and 43 open issues. Those issue numbers are worth reading carefully: a project with a large public audience and a small open issue queue is a project that closes things, which is a healthier signal than raw popularity.

## Three commands and one prerequisite you cannot skip

The getting started section is numbered, which is unusual for a README of this size and tells you the authors expect a large fraction of readers to be running it for the first time.

Step one is environment setup. The note states that the WinUI Gallery requires Visual Studio 2022 or later to build and Windows 10 or later to execute, and points first-time builders at separate installation instructions. The required Visual Studio component is listed narrowly: Windows application development. That single workload is what brings in the Windows App SDK templates and toolchain, and it is the item most likely to be missing from an installation that otherwise looks correct.

Step two is the clone, and it is the only command in the whole README:

```powershell
git clone https://github.com/microsoft/WinUI-Gallery.git
```

Step three is to open `WinUIGallery.slnx` with Visual Studio and build, ensuring the `WinUIGallery` project is set as the startup project. The solution extension is worth pausing on. A `.slnx` file is the newer XML-based solution format rather than the legacy binary `.sln`, and its presence at the root of a Microsoft-maintained C# repository is a small but real signal about how the team expects modern Windows projects to be opened and shared. The tree listing confirms `WinUIGallery.slnx` is the only solution file, so there is no fallback path for tooling that still expects the old format.

There is no separate step for selecting an SDK version, no script to run before opening, and no database or service to start. That simplicity is the reward for the Gallery being a plain desktop application rather than a hosted product, and it is the main practical reason this repository is approachable on a machine that has never built a Windows App SDK project.

## Why the SDK version is pinned instead of resolved

The most consequential paragraph in the README is easy to skim past, because it sits in the getting started section with no heading of its own. The Gallery uses an experimental Windows App SDK to demonstrate upcoming features. Use the normal `Debug` or `Release` configuration, with the SDK version pinned in `standalone.props`. The runtime is bundled with the app, which the README calls self-contained deployment, instead of referencing a shared Windows App SDK framework package. And the warning that closes the paragraph is that experimental APIs can change or be removed before a stable release.

Three separate decisions are compressed there, and each one has consequences for anyone learning from the samples.

Pinning the SDK version in a file named `standalone.props`, rather than letting NuGet resolve the newest package, means the repository builds against a known-good build even after newer experimental packages ship. That is the right choice for a reference app, and it also means the file is the single place to look when a sample behaves differently on your machine than it does on main. The property file name is unusual enough to be memorable, which helps, because it is the file you will be reading when the question is which SDK version this sample was authored against.

Self-contained deployment removes an entire class of confusion from a shared-framework model. A machine that has never run a Windows App SDK application can run the Gallery without installing a matching runtime first. For a gallery meant to be handed to developers as a starting point, that removes the single most common first-run failure.

The third decision has a cost. Because the Gallery deliberately builds against experimental APIs, some sample code will stop compiling after an SDK update, and a feature demonstrated on a page may not exist in the version of WinUI you have installed. The Windowing APIs page makes this explicit by combining stable window creation with experimental window sizing examples, where each experimental example carries its own label and warning and the stable example retains its original APIs. That labelling convention is the pattern to follow if you copy anything from here.

## The build failure Microsoft documented in its own README

Most READMEs tell you how the project is supposed to build. This one also tells you how to recover when it does not, which is the part most worth reading.

The warning block says to try deleting `nuget.config` and building again if a specific build error appears: the assets file at a path under `WinUIGallery\obj\WinUIGallery\project.assets.json` was not found, with NuGet advising a package restore to generate it. The README links this to issue 1659, titled Broken repo build.

This is a real and slightly unusual admission. The proposed fix is to remove a checked-in configuration file, which is the opposite of what most documentation would advise. The likely mechanism is that the committed `nuget.config` points restore at a specific feed or package source whose behaviour changed, and deleting it falls back to the machine's default NuGet configuration, which resolves the packages successfully. The repository tree confirms `nuget.config` is present at the root, so the file genuinely ships with the project.

The fact that the workaround is in the README rather than only in the issue thread suggests it works often enough to be worth documenting, and it also suggests the underlying restore configuration has not been permanently fixed. If you hit it, follow the instruction. If you are thinking of forking the Gallery for internal use, that file is the first thing to examine, because your build will inherit the same fragility until you understand why it is there.

## Reading the tree as an argument about structure

The root listing is short enough to read at a glance and dense enough to reward reading, so it is worth walking through rather than skipping.

`WinUIGallery/` is the application itself. `WinUIGallery.SourceGenerator/` is the more interesting sibling, and its existence tells you that part of the Gallery's metadata is produced at compile time by a Roslyn source generator rather than hand-maintained. For a project whose job is to keep dozens of sample pages consistent, generating the plumbing is how you avoid a hundred hand-edited files drifting apart, and it is the kind of infrastructure that most sample repositories skip.

`catalog/` and `packagestore/` are two directories that only make sense once you know the Gallery supports both packaged and unpackaged deployment modes. That support is confirmed by a refactor in the v2.8.0 release notes titled Application Settings and Support for Packaged/Unpackaged Mode, tied to issue 1924. Packaged means a Store-installed app with an identity; unpackaged means it runs directly from disk. Supporting both in one codebase is a non-trivial requirement, and the dedicated directories show where that complexity lives.

`tests/` exists, which is worth noting for a sample application. `tools/` and `scripts/` cover the supporting automation, and `.pipelines/` indicates the build and publishing definitions. `docs/` is not just documentation: it holds `PublishingNewVersion.md`, the release runbook that maintainers follow to coordinate Microsoft Store publishing with a GitHub release. `Directory.Build.props` and `.editorconfig` at the root are the two files that make formatting and build settings uniform across every project in the solution, and `SECURITY.md` sits next to `LICENSE`, so there is a stated path for reporting a vulnerability in the Gallery itself.

## What three releases say about where the effort goes

The release history is short but unusually legible, because each entry is a list of pull requests with an author attached. Reading them together gives a clearer picture of the maintenance priorities than any single entry does.

Version 2.9.0, published 2026-05-01, is dominated by warning cleanup. Fix general warnings in the project excluding settings infrastructure, then fix nullability warnings in the settings infrastructure, then fix the remaining warnings, as three separate pull requests. Nullability annotations in C# are what let the compiler tell you a reference might be null, so cleaning those up across a project of this size is real work with a real payoff: it moves errors from runtime to compile time. The same release carries user-visible fixes including an animation interop sample correction, two additional NavigationTransitionInfos, a modal window sample that was not being scaled for DPI, a ContentIsland page leak, and a typo in a ContentDialog description. The DPI scaling fix and the memory leak fix are the two that matter most, because they are the class of bug that makes a sample teach the wrong thing.

Version 2.8.0, published 2026-03-05, is more user-facing still. It enhances icon tags with British variants and synonyms, fixes a SplitView sample layout issue when the pane is on the right, corrects word spacing in a TextBlock sample, fixes a corner radius mismatch between a GridViewItem and its item template, and fixes a clipped Hyperlink focus rectangle on the typography page. It also fixes grammar in the high contrast section text. A clipped focus rectangle and high contrast wording are accessibility concerns, and the fact that they were fixed in a sample app is a reasonable proxy for how seriously the design guidance in the app is taken.

Version 2.9.3, published 2026-05-27, is the most instructive because of what it implies. It is described as a minor release to adjust WinUI 3 Gallery code links to match the new project structure, and the three changes are restructure samples, hide the copy button on ColorsPage, and convert other samples. A release whose purpose is fixing links because the directory layout moved is an admission that the Gallery's structure is expensive to change. For a repository that exists to hold hundreds of small sample files, that is the natural cost, and the team is clearly doing it deliberately rather than accumulating a restructure backlog.

## Conclusion

The Gallery earns its place in a Windows developer's reading list because it is honest about what it is: a moving target that pins an experimental SDK, restructured often enough that its own release notes mention broken code links, and willing to publish a workaround for its own build failure in the README. Treat the sample pages as a reference for how Microsoft wants WinUI 3 used, and treat `standalone.props` as the file that tells you which SDK build a given sample was actually written against.

## FAQ

### What is WinUI 3 Gallery used for?

It is a reference application for building modern Windows desktop apps. The README describes it as a companion app for WinUI and Windows App SDK APIs and the interactive companion to the Fluent Design guidelines, with each control page showing the markup and codebehind used to create the example, plus separate design and accessibility pages.

### How do I build the WinUI 3 Gallery from source?

You need Visual Studio 2022 or later on Windows to build and Windows 10 or later to run, with the Windows application development workload installed. Clone the repository with git, open `WinUIGallery.slnx`, make sure the `WinUIGallery` project is the startup project, and build with the normal Debug or Release configuration.

### Why does the Gallery use an experimental Windows App SDK build?

So it can demonstrate upcoming features rather than only stable ones. The SDK version is pinned in `standalone.props` and the runtime is bundled with the app using self-contained deployment instead of a shared framework package. The README warns that experimental APIs can change or be removed before a stable release, which is why experimental examples on pages carry their own labels.

## Sources

- [License: MIT](https://github.com/microsoft/WinUI-Gallery/blob/main/LICENSE)
- [microsoft/WinUI-Gallery on GitHub](https://github.com/microsoft/WinUI-Gallery)
- [Project website](https://aka.ms/winui)
- [README](https://github.com/microsoft/WinUI-Gallery/blob/main/README.md)
- [Releases](https://github.com/microsoft/WinUI-Gallery/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/microsoft-winui-gallery