openai-winui-app/references/foundation-winui-app-structure.md

---

title: WinUI App Structure priority: HIGH tags: app-structure, xaml, resources, pages, bindings, csharp sources: - https://github.com/microsoft/WinUI-Gallery - https://learn.microsoft.com/windows/apps/winui/

---

What This Reference Is For

Use this file when structuring a WinUI 3 app, reviewing project layout, or deciding where shell, pages, controls, resources, and view models should live.

Prefer

• A clear C#-first folder split such as Pages, Controls, ViewModels, Services, Styles, and Assets.
• App.xaml and shared resource dictionaries for app-wide theme resources and styles.
• A single main shell window that owns navigation and common chrome.
• Native command surfaces such as CommandBar for grouped window or page actions before inventing a custom toolbar composition.
• Strongly typed x:Bind where it improves compile-time safety and performance.

Avoid

• Putting shell logic, page logic, and resource definitions into one large window file.
• Scattering theme brushes and styles across many page-local dictionaries.
• Introducing MVVM ceremony that the project will not actually maintain.

Recommended Shape

• App.xaml / App.xaml.cs
• global resources, startup, window creation, app-level exceptions
• MainWindow.xaml / MainWindow.xaml.cs
• shell, title bar, top-level navigation host
• Pages/
• page views and page-specific logic
• Controls/
• reusable WinUI user controls
• ViewModels/
• state and commands when the app benefits from separation
• Styles/
• resource dictionaries, theme tokens, shared control styles
• Helpers/ or Services/
• windowing, navigation, persistence, OS integration helpers

Binding Guidance

• Prefer x:Bind for page-local properties, event handlers, and strongly typed view model access.
• Use Binding where the data context is dynamic or a template must stay flexible.
• Avoid binding patterns that depend on unclear page lifetime or implicit data contexts.

WinUI Gallery Anchors

• App.xaml.cs shows app-level startup and integration points.
• MainWindow.xaml shows shell composition, title bar usage, and search integration.
• Pages/ and Samples/ show how Microsoft organizes pages, helpers, and styles in a real WinUI companion app.

Review Checklist

• Are app resources centralized?
• Is shell logic separated from content pages?
• Are bindings explicit and maintainable?
• Is the structure consistent with the scale of the app?