winui

WinUI 3 and Windows App SDK

Trigger On

• building native modern Windows desktop UI on WinUI 3
• integrating Windows App SDK features into a .NET app
• deciding between WinUI, WPF, WinForms, and MAUI for Windows work
• implementing MVVM patterns in Windows App SDK applications

Workflow

1. Confirm WinUI is the right choice — use when modern Windows-native UI, Fluent Design, and Windows App SDK capabilities are needed. For cross-platform, consider MAUI instead.
2. Choose packaging model early — packaged (MSIX) vs unpackaged differ materially for deployment, identity, and API access:

   <!-- Unpackaged: add to .csproj -->
   <WindowsPackageType>None</WindowsPackageType>
   

3. Apply MVVM pattern with the MVVM Toolkit — keep views dumb, logic in ViewModels:

   public partial class ProductsViewModel : ObservableObject
   {
       [ObservableProperty]
       private ObservableCollection<Product> _products = [];
   
       [ObservableProperty]
       [NotifyCanExecuteChangedFor(nameof(DeleteCommand))]
       private Product? _selectedProduct;
   
       [RelayCommand(CanExecute = nameof(CanDelete))]
       private async Task DeleteAsync()
       {
           if (SelectedProduct is null) return;
           await _productService.DeleteAsync(SelectedProduct.Id);
           Products.Remove(SelectedProduct);
       }
       private bool CanDelete() => SelectedProduct is not null;
   }
   

4. Use x:Bind for compiled bindings — better performance and compile-time checking than {Binding}:

   <TextBlock Text="{x:Bind ViewModel.Title, Mode=OneWay}"/>
   

5. Wire DI through Host.CreateDefaultBuilder — register services, ViewModels, and views. Resolve via App.GetService<T>().
6. Implement navigation service — map ViewModels to Pages by convention. See references/patterns.md for the full pattern.
7. Handle Windows App SDK features — windowing (AppWindow), custom title bar, app lifecycle, notifications.
8. Always set XamlRoot when showing ContentDialog — omitting this causes silent failures.
9. Validate on Windows targets — behavior depends on runtime, packaging model, and Windows version.