Winui3

# WinUI 3 / Windows App SDK

Critical Rules — NEVER Use Legacy UWP APIs

These UWP patterns are **wrong** for WinUI 3 desktop apps. Always use the Windows App SDK equivalent.

- **NEVER** use `Windows.UI.Popups.MessageDialog`. Use `ContentDialog` with `XamlRoot` set.

- **NEVER** show a `ContentDialog` without setting `dialog.XamlRoot = this.Content.XamlRoot` first.

- **NEVER** use `CoreDispatcher.RunAsync` or `Dispatcher.RunAsync`. Use `DispatcherQueue.TryEnqueue`.

- **NEVER** use `Window.Current`. Track the main window via a static `App.MainWindow` property.

- **NEVER** use `Windows.UI.Xaml.*` namespaces. Use `Microsoft.UI.Xaml.*`.

- **NEVER** use `Windows.UI.Composition`. Use `Microsoft.UI.Composition`.

- **NEVER** use `Windows.UI.Colors`. Use `Microsoft.UI.Colors`.

- **NEVER** use `ApplicationView` or `CoreWindow` for window management. Use `Microsoft.UI.Windowing.AppWindow`.

- **NEVER** use `CoreApplicationViewTitleBar`. Use `AppWindowTitleBar`.

- **NEVER** use `GetForCurrentView()` patterns (e.g., `UIViewSettings.GetForCurrentView()`). These do not exist in desktop WinUI 3. Use `AppWindow` APIs instead.

- **NEVER** use UWP `PrintManager` directly. Use `IPrintManagerInterop` with a window handle.

- **NEVER** use `DataTransferManager` directly for sharing. Use `IDataTransferManagerInterop` with a window handle.

- **NEVER** use UWP `IBackgroundTask`. Use `Microsoft.Windows.AppLifecycle` activation.

- **NEVER** use `WebAuthenticationBroker`. Use `OAuth2Manager` (Windows App SDK 1.7+).

XAML Patterns

- The default XAML namespace maps to `Microsoft.UI.Xaml`, not `Windows.UI.Xaml`.

- Prefer `{x:Bind}` over `{Binding}` for compiled, type-safe, higher-performance bindings.

- Set `x:DataType` on `DataTemplate` elements when using `{x:Bind}` — this is required for compiled bindings in templates. On Page/UserControl, `x:DataType` enables compile-time binding validation but is not strictly required if the DataContext does not change.

- Use `Mode=OneWay` for dynamic values, `Mode=OneTime` for static, `Mode=TwoWay` only for editable inputs.

- Do not bind static constants — set them directly in XAML.

Threading

- Use `DispatcherQueue.TryEnqueue(() => { ... })` to update UI from background threads.

- `TryEnqueue` returns `bool`, not a `Task` — it is fire-and-forget.

- Check thread access with `DispatcherQueue.HasThreadAccess` before dispatching.

- WinUI 3 uses standard STA (not ASTA). No built-in reentrancy protection — be cautious with async code that pumps messages.

Windowing

- Get the `AppWindow` from a WinUI 3 `Window` via `WindowNative.GetWindowHandle` → `Win32Interop.GetWindowIdFromWindow` → `AppWindow.GetFromWindowId`.

- Use `AppWindow` for resize, move, title, and presenter operations.

- Custom title bar: use `AppWindow.TitleBar` properties, not `CoreApplicationViewTitleBar`.

- Track the main window as `App.MainWindow` (a static property set in `OnLaunched`).

Dialogs and Pickers

- **ContentDialog**: Always set `dialog.XamlRoot = this.Content.XamlRoot` before calling `ShowAsync()`.

- **File/Folder Pickers**: Initialize with `WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd)` where `hwnd` comes from `WindowNative.GetWindowHandle(App.MainWindow)`.

- **Share/Print**: Use COM interop interfaces (`IDataTransferManagerInterop`, `IPrintManagerInterop`) with window handles.

MVVM and Data Binding

- Prefer `CommunityToolkit.Mvvm` (`[ObservableProperty]`, `[RelayCommand]`) for MVVM infrastructure.

- Use `Microsoft.Extensions.DependencyInjection` for service registration and injection.

- Keep UI (Views) focused on layout and bindings; keep logic in ViewModels and services.

- Use `async`/`await` for I/O and long-running work to keep the UI responsive.

Project Setup

- Target `net10.0-windows10.0.22621.0` (or appropriate TFM for the project's target SDK).

- Set `<UseWinUI>true</UseWinUI>` in the project file.

- Reference the latest stable `Microsoft.WindowsAppSDK` NuGet package.

- Use `System.Text.Json` wi