diff --git a/hub/apps/develop/ai-assisted/images/arch.png b/hub/apps/develop/ai-assisted/images/arch.png new file mode 100644 index 0000000000..fd97231a6e Binary files /dev/null and b/hub/apps/develop/ai-assisted/images/arch.png differ diff --git a/hub/apps/develop/ai-assisted/images/myfirstapp.png b/hub/apps/develop/ai-assisted/images/myfirstapp.png new file mode 100644 index 0000000000..9d15f11b72 Binary files /dev/null and b/hub/apps/develop/ai-assisted/images/myfirstapp.png differ diff --git a/hub/apps/develop/ai-assisted/index.md b/hub/apps/develop/ai-assisted/index.md new file mode 100644 index 0000000000..f572a019c6 --- /dev/null +++ b/hub/apps/develop/ai-assisted/index.md @@ -0,0 +1,137 @@ +--- +title: AI-assisted Windows development +description: Build Windows apps faster using AI agents, GitHub Copilot, Claude Code, and the Windows AI development toolkit — with tools that are free, work in VS Code, and require no prior Windows experience. +ms.topic: overview +ms.date: 05/13/2026 +ms.author: jken +author: GrantMeStrength +--- + +# AI-assisted Windows development + +Windows has a complete set of free, AI-ready tools that take you from idea to published app — entirely from the command line or VS Code, without needing Visual Studio. Whether you're building a new app from scratch or modernizing one you wrote years ago, AI agents can do the heavy lifting. + +:::image type="content" source="images/arch.png" alt-text="Architecture diagram showing a developer writing prompts into VS Code, where GitHub Copilot and Claude Code AI agents use the WinUI Agent Plugin and winui-ui-testing skill from the Knowledge Layer, and query the Microsoft Learn MCP Server for live API docs, to generate correct WinUI 3 code targeting the Windows App SDK and .NET 10."::: + +> [!TIP] +> New to Windows development? Start with the [Quickstart: Build and publish a Windows app with AI](quickstart.md) — you can have a working app in under 30 minutes using only free tools. + +--- + +## What path are you on? + +:::row::: + :::column::: + ### I'm starting fresh + Use the `winui-dev` agent and `dotnet new` templates to scaffold, build, run, and publish a new Windows app — no Windows experience required. + + → [Quickstart](quickstart.md) + → [WinUI agent plugin](winui-agent-plugin.md) + :::column-end::: + :::column::: + ### I have an existing app + AI tools can help you migrate WPF, WinForms, or UWP apps to modern WinUI 3, or add Windows capabilities to apps built with Electron, Flutter, Tauri, or Rust. + + → [Migrate from WPF](migrate/wpf-to-winui.md) + → [Migrate from UWP](migrate/uwp-to-winui.md) + → [Cross-framework apps](migrate/cross-framework.md) + :::column-end::: +:::row-end::: + +--- + +## Tools in this section + +| Tool | What it does | +|------|-------------| +| **[WinUI agent plugin](winui-agent-plugin.md)** | 8 skills for end-to-end WinUI development in GitHub Copilot or Claude Code | +| **[VS Code tools](vs-code-tools.md)** | WinApp extension + Microsoft Learn MCP Server for VS Code and Claude Code | +| **[AI-assisted testing](testing.md)** | Generate and run UI tests using Windows UI Automation | +| **[Publish to the Store](quickstart.md#step-5-publish-to-the-microsoft-store)** | Submit to the Microsoft Store from the command line using `winapp store` | + +--- + +## Frequently asked questions + +### Can I build a WinUI 3 app without Visual Studio? + +Yes. Three commands are all you need: + +```powershell +dotnet new winui-navview -n MyApp +cd MyApp +dotnet run +``` + +Build, debug, package, and publish from VS Code or the terminal. Visual Studio is still best for complex XAML debugging, but it's no longer required. See the [Quickstart](quickstart.md). + +### Are these tools free? + +Yes — the WinApp CLI, VS Code extension, and `dotnet new` templates are free and open source. GitHub Copilot requires a [subscription](https://github.com/features/copilot) (free tier available). The [Microsoft Learn MCP Server](vs-code-tools.md#microsoft-learn-mcp-server) is free with no sign-in required. + +### Will Copilot give me outdated UWP code instead of WinUI 3? + +By default, yes. AI models have more UWP training data than WinUI 3, so they drift toward deprecated patterns (`Windows.UI.Xaml`, `CoreDispatcher`, `MessageDialog`). Two tools fix this: the [WinUI agent plugin](winui-agent-plugin.md) injects correct WinUI 3 rules as custom instructions, and the [Microsoft Learn MCP Server](vs-code-tools.md#microsoft-learn-mcp-server) gives your agent live access to current docs. + +### Does this work with Claude Code as well as GitHub Copilot? + +Yes. The `winui@awesome-copilot` plugin and the Microsoft Learn MCP Server both work with any MCP-compatible agent. + +### How long does it take to go from idea to published app? + +Under 30 minutes to a running app (see the [Quickstart](quickstart.md)). Store submission requires a [Partner Center account](https://partner.microsoft.com/dashboard) and certification, which typically takes 1–3 business days. + +--- + +## Starter prompts + +AI models have years of UWP and WPF training data — these prompts override that and anchor responses to current WinUI 3 patterns. + +> [!TIP] +> To avoid adding these WinUI 3 constraints to every prompt, install the [WinUI agent plugin](winui-agent-plugin.md). It injects them automatically as system-level instructions, so you can write simple requests like *"Build me a WinUI 3 app that shows files in a folder"* without spelling out the API rules each time. + +### New app + +``` +Create a new WinUI 3 Windows app using `dotnet new winui-navview` (from the +Microsoft.WindowsAppSDK.WinUI.CSharp.Templates package). Build and run with the +winapp CLI — not Visual Studio. + +Use Microsoft.UI.Xaml for all controls — never Windows.UI.Xaml. +Use DispatcherQueue, not CoreDispatcher. +Use AppWindow + OverlappedPresenter, not ApplicationView. +Use ContentDialog, not MessageDialog. +``` + +### Migrate from UWP or WPF + +``` +I'm migrating a [UWP / WPF] app to WinUI 3 using the Windows App SDK. + +Apply these substitutions: +- Windows.UI.Xaml.* → Microsoft.UI.Xaml.* +- CoreDispatcher / Dispatcher.RunAsync → DispatcherQueue.TryEnqueue +- ApplicationView → AppWindow + OverlappedPresenter +- MessageDialog → ContentDialog +- Windows.UI.Notifications → Microsoft.Windows.AppNotifications +- Frame.Navigate with UWP page types → WinUI 3 Frame + Page + +Do not introduce any Windows.UI.* APIs. Flag anything without a direct WinUI 3 equivalent. +``` + +### Add a feature to an existing WinUI 3 app + +``` +This is a WinUI 3 app using the Windows App SDK. +- Use Microsoft.UI.Xaml.* namespaces only +- Use DispatcherQueue for thread marshalling +- Use CommunityToolkit.Mvvm for MVVM patterns +- Use winapp run to test — do not open Visual Studio +``` + +--- + +## Related content + +- [Windows App Development CLI](../../dev-tools/winapp-cli/index.md) +- [Security and responsible AI](security-and-responsible-ai.md) diff --git a/hub/apps/develop/ai-assisted/migrate/cross-framework.md b/hub/apps/develop/ai-assisted/migrate/cross-framework.md new file mode 100644 index 0000000000..98cc36fc83 --- /dev/null +++ b/hub/apps/develop/ai-assisted/migrate/cross-framework.md @@ -0,0 +1,70 @@ +--- +title: "Cross-framework app considerations" +description: Build Windows apps that share business logic across WinUI 3, MAUI, and other frameworks using the Windows App SDK. +ms.topic: overview +ms.date: 05/13/2026 +ms.author: jken +author: GrantMeStrength +--- + +# Cross-framework app considerations + +You may be coming to WinUI 3 from React Native Windows, Electron, Flutter, or .NET MAUI. This page covers what to expect when targeting WinUI 3 specifically, and how to set up your AI agent for success. + +The key decision: do you want to keep a cross-platform shell, or build a Windows-first app? Give your AI agent a clear boundary — which business logic stays shared, and which UI should be rewritten as native WinUI 3. + +## React Native for Windows + +React Native for Windows uses a WinUI rendering layer under the hood. You can integrate native Windows controls through `` or NativeModules. + +For a fully native Windows experience, porting directly to WinUI 3 gives better performance and full Windows API access. Keep business logic and services, but rewrite UI components as XAML and C#. + +Starter prompt: +```text +I have a React Native for Windows component. Rewrite it as a WinUI 3 UserControl using C# and XAML. +``` + +## Electron + +Electron apps are web technology wrapped in a shell; WinUI 3 is native Win32. A practical incremental path is to host your existing web UI in a WinUI 3 window using WebView2, then migrate features to native controls over time. + +Starter prompt: +```text +I have an Electron app. Create a WinUI 3 shell that hosts a WebView2, and show me how to call native Windows APIs from the web layer using window.chrome.webview.postMessage. +``` + +## .NET MAUI + +.NET MAUI already targets Windows via WinUI 3. If you want a Windows-only experience with full WinUI 3 control, remove MAUI and target WinUI 3 directly. + +- ViewModels and services move across cleanly +- MAUI XAML (`Microsoft.Maui.Controls.*`) needs rewriting to WinUI 3 XAML (`Microsoft.UI.Xaml.*`) +- Keep shared .NET class libraries as-is + +Starter prompt: +```text +I have a .NET MAUI ViewModel and service layer. Reuse them in a WinUI 3 project targeting Windows only. Keep the ViewModel unchanged and update only the View. +``` + +## Flutter + +Flutter for Windows uses its own rendering engine, not WinUI 3. Platform channels let Flutter call native Win32 or WinRT APIs, but a full port replaces Flutter rendering with native XAML. + +Starter prompt: +```text +I have a Flutter screen with a list and a detail view. Rewrite it as a WinUI 3 page using NavigationView and a master/detail layout. +``` + +## Sharing code across platforms + +- Keep business logic in a separate .NET class library — it's platform-agnostic +- Share that library between WinUI 3, MAUI, Blazor, or any other .NET target +- Reuse models, services, and ViewModels before rewriting UI +- Use `#if WINDOWS` conditional compilation only as a last resort + +## Related content + +- [Migrate and port apps overview](index.md) +- [Migrate from WPF](wpf-to-winui.md) +- [Migrate from UWP](uwp-to-winui.md) +- [Migrate from iOS](ios-to-winui.md) diff --git a/hub/apps/develop/ai-assisted/migrate/index.md b/hub/apps/develop/ai-assisted/migrate/index.md new file mode 100644 index 0000000000..3c75b55287 --- /dev/null +++ b/hub/apps/develop/ai-assisted/migrate/index.md @@ -0,0 +1,36 @@ +--- +title: "Migrate and port apps to WinUI 3" +description: Modernize existing Windows apps by migrating from WPF, UWP, or other frameworks to WinUI 3 and the Windows App SDK using AI assistance. +ms.topic: overview +ms.date: 05/13/2026 +ms.author: jken +author: GrantMeStrength +--- + +# Migrate and port apps to WinUI 3 + +WinUI 3 and the Windows App SDK are the modern foundation for Windows apps. AI tools can automate much of the mechanical migration work — namespace substitutions, API replacements, project file updates — but they need accurate guidance to avoid reproducing outdated patterns. + +The main risk is drift toward older stacks. AI models have more training data for UWP and WPF than for WinUI 3, so provide exact API mappings when prompting for migration code. + +## Choose your migration path + +| From | To | AI skill | Guide | +|------|----|----------|-------| +| WPF (.NET) | WinUI 3 | `winui-wpf-migration` | [Migrate from WPF](wpf-to-winui.md) | +| UWP | WinUI 3 | — | [Migrate from UWP](uwp-to-winui.md) | +| iOS / SwiftUI | WinUI 3 | — | [Migrate from iOS](ios-to-winui.md) | +| React Native / Electron / MAUI / Flutter | WinUI 3 | — | [Cross-framework considerations](cross-framework.md) | + +## Before you start + +- Work in a branch before running large AI-assisted rewrites. +- Verify your dependencies support .NET 10 and Windows App SDK packaging. +- Review the [Windows App SDK migration guide](https://learn.microsoft.com/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/migrate-to-windows-app-sdk-ovw). +- Prepare API mapping tables before prompting — the per-framework pages have them ready to paste. + +## Related content + +- [AI-assisted development overview](../index.md) +- [Quickstart: Build and publish a Windows app with AI](../quickstart.md) +- [WinUI agent plugin](../winui-agent-plugin.md) diff --git a/hub/apps/develop/ai-assisted/migrate/ios-to-winui.md b/hub/apps/develop/ai-assisted/migrate/ios-to-winui.md new file mode 100644 index 0000000000..e2361bd7f7 --- /dev/null +++ b/hub/apps/develop/ai-assisted/migrate/ios-to-winui.md @@ -0,0 +1,82 @@ +--- +title: Migrate an iOS app to WinUI 3 +description: Use AI assistance to port an iOS app to WinUI 3 and the Windows App SDK — mapping UIKit concepts, Swift patterns, and iOS lifecycle events to their WinUI equivalents. +ms.topic: how-to +ms.date: 05/14/2026 +ms.author: jken +author: GrantMeStrength +--- + +# Migrate an iOS app to WinUI 3 + +If you have an iOS app and want to bring it to Windows, AI tools can do most of the mapping work. This page provides the key concept translations from UIKit/SwiftUI to WinUI 3. Use these tables as context when prompting your AI agent — providing exact API mappings up front produces far more accurate output than asking for a generic conversion. + +Install the [WinUI agent plugin](../winui-agent-plugin.md) first to give your agent accurate WinUI 3 knowledge: + +```powershell +gh copilot plugin install winui@awesome-copilot +``` + +## Concept mapping + +| iOS (UIKit / SwiftUI) | WinUI 3 equivalent | Notes | +|---|---|---| +| `UIViewController` | `Page` | WinUI pages are navigated via `Frame` | +| `UINavigationController` | `Frame` + `NavigationView` | Use `Frame.Navigate()` for page transitions | +| `UITabBarController` | `NavigationView` (top or left tabs) | | +| `UITableView` | `ListView` | Use `ObservableCollection` for data binding | +| `UICollectionView` | `GridView` | | +| `UIAlertController` | `ContentDialog` | Must be parented to the current `XamlRoot` | +| `UILabel` | `TextBlock` | | +| `UITextField` | `TextBox` | | +| `UIButton` | `Button` | | +| `UIImageView` | `Image` | | +| `UIStackView` | `StackPanel` | Set `Orientation` to `Horizontal` or `Vertical` | +| `Auto Layout` | `Grid` / `StackPanel` / `RelativePanel` | XAML layout is row/column based | +| `@State` / `@Binding` (SwiftUI) | `INotifyPropertyChanged` / `ObservableProperty` (CommunityToolkit.Mvvm) | | +| `NSUserDefaults` | `ApplicationData.Current.LocalSettings` | | +| `URLSession` | `HttpClient` | Use `System.Net.Http.HttpClient` | +| `NotificationCenter` | Events or `WeakReferenceMessenger` (CommunityToolkit.Mvvm) | | +| `DispatchQueue.main.async` | `DispatcherQueue.TryEnqueue` | | +| `AppDelegate.applicationDidFinishLaunching` | `App.OnLaunched` | | +| `SceneDelegate` / `windowScene` | `MainWindow` / `AppWindow` | | +| `FileManager` | `StorageFolder` / `StorageFile` | | +| `UserNotifications` | `AppNotificationManager` (Microsoft.Windows.AppNotifications) | | + +## Starter prompt + +Use this prompt to give your AI agent the context it needs before starting a migration: + +``` +I'm migrating an iOS app to WinUI 3 using the Windows App SDK. + +The app is written in [Swift / Objective-C] using [UIKit / SwiftUI]. + +Apply these mappings: +- UIViewController → Page, navigated via Frame +- UINavigationController → Frame + NavigationView +- UITableView → ListView with ObservableCollection +- UIAlertController → ContentDialog (parented to XamlRoot) +- NSUserDefaults → ApplicationData.Current.LocalSettings +- URLSession → System.Net.Http.HttpClient +- DispatchQueue.main.async → DispatcherQueue.TryEnqueue +- @State / @Binding → INotifyPropertyChanged via CommunityToolkit.Mvvm + +Use Microsoft.UI.Xaml.* namespaces throughout — never Windows.UI.Xaml.*. +Generate C# — not Swift. +``` + +## What doesn't map directly + +Some iOS concepts don't have a direct WinUI equivalent: + +- **In-app purchases**: Use the [Microsoft Store commerce APIs](https://learn.microsoft.com/windows/uwp/monetize/) via `Windows.Services.Store` +- **Push notifications (APNs)**: Use [Windows Push Notification Services (WNS)](../../notifications/push-notifications/wns-overview.md) +- **HealthKit / ARKit / CoreML**: Windows has related technology areas — [Windows ML](https://learn.microsoft.com/windows/ai/windows-ml/), [Windows Mixed Reality](https://learn.microsoft.com/windows/mixed-reality/), and [Windows Sensors](https://learn.microsoft.com/windows/uwp/devices-sensors/sensors) — but these are not direct equivalents and require platform-specific implementation +- **App Clips**: No direct equivalent — consider [web-to-app linking](https://learn.microsoft.com/windows/uwp/launch-resume/web-to-app-linking) + +## Related content + +- [Migrate from UWP](uwp-to-winui.md) +- [WinUI agent plugin](../winui-agent-plugin.md) +- [Microsoft Learn MCP Server](../vs-code-tools.md#microsoft-learn-mcp-server) diff --git a/hub/apps/develop/ai-assisted/migrate/uwp-to-winui.md b/hub/apps/develop/ai-assisted/migrate/uwp-to-winui.md new file mode 100644 index 0000000000..8ba86ed4c7 --- /dev/null +++ b/hub/apps/develop/ai-assisted/migrate/uwp-to-winui.md @@ -0,0 +1,160 @@ +--- +title: Migrate a UWP app to WinUI 3 +description: Port a UWP app to WinUI 3 and the Windows App SDK using AI assistance — with a complete API substitution table covering namespaces, controls, threading, windowing, notifications, and more. +ms.topic: how-to +ms.date: 05/14/2026 +ms.author: jken +author: GrantMeStrength +--- + +# Migrate a UWP app to WinUI 3 + +UWP is no longer under active development. WinUI 3 and the Windows App SDK are its successors — and AI tools can automate most of the migration. The main challenge is that AI models were trained on years of UWP samples, so without guidance they reproduce the patterns you're trying to move away from. This page gives your agent the context it needs to get it right. + +## Install the WinUI agent plugin + +The `winui-uwp-migration` skill handles the common substitutions automatically: + +```powershell +gh copilot plugin install winui@awesome-copilot +``` + +See the [WinUI agent plugin](../winui-agent-plugin.md) for full details. + +## API substitution table + +### Namespaces + +| UWP | WinUI 3 | +|-----|---------| +| `Windows.UI.Xaml.*` | `Microsoft.UI.Xaml.*` | +| `Windows.UI.Xaml.Controls.*` | `Microsoft.UI.Xaml.Controls.*` | +| `Windows.UI.Xaml.Media.*` | `Microsoft.UI.Xaml.Media.*` | +| `Windows.UI.Composition` | `Microsoft.UI.Composition` | + +### Threading + +| UWP | WinUI 3 | +|-----|---------| +| `CoreDispatcher` | `DispatcherQueue` | +| `Dispatcher.RunAsync(...)` | `DispatcherQueue.TryEnqueue(...)` | +| `CoreApplication.MainView.CoreWindow.Dispatcher` | `this.DispatcherQueue` (from a `Window` or `Page`) | + +### Windowing + +| UWP | WinUI 3 | +|-----|---------| +| `ApplicationView` | `AppWindow` | +| `ApplicationView.GetForCurrentView()` | `AppWindow.GetFromWindowId(...)` | +| `ApplicationViewTitleBar` | `AppWindowTitleBar` | +| `CoreWindow` | `Microsoft.UI.Xaml.Window` | +| `SystemNavigationManager` | Back button via `AppWindowTitleBar` | + +### Dialogs and pickers + +| UWP | WinUI 3 | +|-----|---------| +| `MessageDialog` | `ContentDialog` (set `XamlRoot`) | +| `FileOpenPicker` | `FileOpenPicker` + `InitializeWithWindow` | +| `FileSavePicker` | `FileSavePicker` + `InitializeWithWindow` | +| `FolderPicker` | `FolderPicker` + `InitializeWithWindow` | + +> [!IMPORTANT] +> **Pickers** require `InitializeWithWindow` before calling `PickSingleFileAsync` (or similar): +> +> ```csharp +> var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow); +> WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd); +> ``` +> +> **ContentDialog** requires `XamlRoot` (not `InitializeWithWindow`): +> +> ```csharp +> var dialog = new ContentDialog { XamlRoot = this.Content.XamlRoot, ... }; +> await dialog.ShowAsync(); +> ``` + +### Notifications + +| UWP | WinUI 3 | +|-----|---------| +| `Windows.UI.Notifications.ToastNotificationManager` | `Microsoft.Windows.AppNotifications.AppNotificationManager` | +| `Windows.UI.Notifications.BadgeUpdateManager` | `Microsoft.Windows.BadgeNotifications.BadgeNotificationManager` | +| `Windows.UI.Notifications.TileUpdateManager` | Tiles are deprecated — use notifications or widgets | + +### Navigation + +| UWP | WinUI 3 | +|-----|---------| +| `Frame.Navigate(typeof(MyPage))` | `Frame.Navigate(typeof(MyPage))` — unchanged | +| `SystemNavigationManager.BackRequested` | Handle via `NavigationView` or `AppWindow` | +| `Windows.UI.Core.Preview.SystemNavigationManagerPreview` | `AppWindow.Closing` event | + +### App lifecycle + +| UWP | WinUI 3 | +|-----|---------| +| `Application.Current.Suspending` | `Microsoft.Windows.AppLifecycle` (requires architectural changes — see note) | +| `Application.Current.Resuming` | `AppInstance.GetCurrent().Activated` (see note) | +| `BackgroundTaskBuilder` | [Windows App SDK background tasks](../../../../windows-app-sdk/applifecycle/applifecycle-rich-activation.md) | + +> [!NOTE] +> WinUI 3 app lifecycle migration is not a simple API name swap. The Windows App SDK uses a different activation and suspension model. Treat lifecycle code as requiring a dedicated rewrite rather than automated substitution. See the [Windows App SDK lifecycle documentation](../../../../windows-app-sdk/applifecycle/applifecycle-rich-activation.md) for the full model. + +### Settings and storage + +| UWP | WinUI 3 | +|-----|---------| +| `ApplicationData.Current.LocalSettings` | Unchanged | +| `ApplicationData.Current.LocalFolder` | Unchanged | +| `Windows.Storage.KnownFolders` | Unchanged | + +### APIs that don't change + +`Windows.Devices.*`, `Windows.Media.*`, `Windows.UI.ViewManagement.UISettings`, `Windows.UI.Color`, and most WinRT APIs outside the XAML namespace are unchanged. + +## Starter prompt + +``` +I'm migrating a UWP app to WinUI 3 using the Windows App SDK. + +Apply these substitutions: +- Windows.UI.Xaml.* → Microsoft.UI.Xaml.* +- CoreDispatcher / Dispatcher.RunAsync → DispatcherQueue.TryEnqueue +- ApplicationView → AppWindow + AppWindowTitleBar +- CoreWindow → Microsoft.UI.Xaml.Window +- MessageDialog → ContentDialog (set XamlRoot, not InitializeWithWindow) +- FileOpenPicker / FileSavePicker / FolderPicker → add InitializeWithWindow +- Windows.UI.Notifications → Microsoft.Windows.AppNotifications +- SystemNavigationManager.BackRequested → NavigationView back handling + +Do not use any Windows.UI.Xaml.* namespaces in new code. +Do not use CoreDispatcher — use DispatcherQueue. +Flag any APIs without a direct WinUI 3 equivalent rather than guessing. +``` + +## Project file changes + +Replace the UWP target framework: + +```xml + +10.0.19041.0 +10.0.17763.0 + + +net10.0-windows10.0.19041.0 +10.0.19041.31 +``` + +Add the Windows App SDK package: + +```powershell +dotnet add package Microsoft.WindowsAppSDK +``` + +## Related content + +- [WinUI agent plugin](../winui-agent-plugin.md) +- [Migrate from WPF](wpf-to-winui.md) +- [Windows App SDK migration guide](https://learn.microsoft.com/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/migrate-to-windows-app-sdk-ovw) diff --git a/hub/apps/develop/ai-assisted/migrate/wpf-to-winui.md b/hub/apps/develop/ai-assisted/migrate/wpf-to-winui.md new file mode 100644 index 0000000000..01fdff3dff --- /dev/null +++ b/hub/apps/develop/ai-assisted/migrate/wpf-to-winui.md @@ -0,0 +1,134 @@ +--- +title: "Migrate a WPF app to WinUI 3" +description: Use the winui-wpf-migration AI skill to port a WPF app to WinUI 3, updating XAML namespaces, controls, and project structure. +ms.topic: overview +ms.date: 05/13/2026 +ms.author: jken +author: GrantMeStrength +--- + +# Migrate a WPF app to WinUI 3 + +WPF apps run on .NET but use the Windows Presentation Foundation XAML stack. WinUI 3 is the modern replacement. The core challenge for AI migration is that WPF uses `System.Windows.*` namespaces while WinUI 3 uses `Microsoft.UI.Xaml.*`, and many controls and windowing APIs need targeted substitutions rather than simple search-and-replace. + +## Install the WPF migration skill + +```powershell +gh copilot plugin install winui@awesome-copilot +``` + +## API substitution table + +### Namespaces + +| WPF | WinUI 3 | +|-----|---------| +| `System.Windows.*` | `Microsoft.UI.Xaml.*` | +| `System.Windows.Controls.*` | `Microsoft.UI.Xaml.Controls.*` | +| `System.Windows.Media.*` | `Microsoft.UI.Xaml.Media.*` | +| `System.Windows.Data.*` | `Microsoft.UI.Xaml.Data.*` | +| `System.Windows.Input.*` | `Microsoft.UI.Input.*` | + +### Controls + +| WPF | WinUI 3 | Notes | +|-----|---------|-------| +| `Window` | `Microsoft.UI.Xaml.Window` | Different API surface | +| `Grid`, `StackPanel`, `Canvas` | Unchanged | Same names | +| `TextBox`, `Button`, `CheckBox` | Unchanged | Same names, WinUI styling | +| `ListBox` / `ListView` | `ListView` | Use `ItemsView` for new code | +| `DataGrid` | `DataGrid` (CommunityToolkit) | Add `CommunityToolkit.WinUI.Controls.DataGrid` | +| `TabControl` | `TabView` | Different API | +| `Menu` / `MenuItem` | `MenuBar` / `MenuBarItem` | | +| `ToolBar` | `CommandBar` | | +| `RichTextBox` | `RichEditBox` | | +| `WebBrowser` | `WebView2` | Different API, async | + +### Threading + +| WPF | WinUI 3 | +|-----|---------| +| `Dispatcher.Invoke(...)` | `DispatcherQueue.TryEnqueue(...)` | +| `Dispatcher.BeginInvoke(...)` | `DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Low, ...)` | +| `Application.Current.Dispatcher` | `this.DispatcherQueue` | + +### Windowing and DPI + +| WPF | WinUI 3 | +|-----|---------| +| `Window.WindowState` | `AppWindow.Presenter` (use `OverlappedPresenter`) | +| `SystemParameters.WorkArea` | `DisplayArea.GetFromWindowId(...)` | +| `PresentationSource.FromVisual()` | `WinRT.Interop.WindowNative.GetWindowHandle(window)` | + +### Data binding + +| WPF | WinUI 3 | +|-----|---------| +| `INotifyPropertyChanged` | Unchanged | +| `ObservableCollection` | Unchanged | +| `{Binding}` | `{x:Bind}` preferred (compile-time) | +| `DependencyProperty` | Unchanged | +| `IValueConverter` | Unchanged | + +### Resources and styles + +| WPF | WinUI 3 | +|-----|---------| +| `ResourceDictionary` | Unchanged | +| `StaticResource` | Unchanged | +| `DynamicResource` | `{ThemeResource}` for system colors | +| `SystemColors.WindowBrush` | `{ThemeResource SystemFillColorSolidNeutralBrush}` | + +## Starter prompt + +```text +I'm migrating a WPF app to WinUI 3 using the Windows App SDK. + +Apply these substitutions: +- System.Windows.* → Microsoft.UI.Xaml.* +- Dispatcher.Invoke / BeginInvoke → DispatcherQueue.TryEnqueue +- Window.WindowState → AppWindow with OverlappedPresenter +- PresentationSource → WinRT.Interop.WindowNative.GetWindowHandle +- DynamicResource for system colors → ThemeResource +- {Binding} → {x:Bind} where possible (compile-time binding) +- ListBox → ListView or ItemsView +- TabControl → TabView +- WebBrowser → WebView2 +- DataGrid → CommunityToolkit.WinUI.Controls.DataGrid + +Do not use any System.Windows.* namespaces in new code. +Do not use Dispatcher.Invoke — use DispatcherQueue.TryEnqueue. +Flag APIs without a direct WinUI 3 equivalent rather than guessing. +``` + +## Project file changes + +```xml + +net10.0-windows +true + + +net10.0-windows10.0.19041.0 +10.0.19041.31 +``` + +```powershell +dotnet add package Microsoft.WindowsAppSDK +``` + +## APIs that don't migrate directly + +Tell the agent to flag these rather than guess: + +- WPF `Adorner` layer — no equivalent in WinUI 3 +- WPF `FlowDocument` / `DocumentViewer` — use `RichEditBox` for editable content; no viewer equivalent +- WPF `Viewport3D` — use Win2D or DirectX interop +- Air-space / HWND hosting — use `SwapChainPanel` or Win32 interop patterns + +## Related content + +- [Migrate from UWP](uwp-to-winui.md) +- [Migrate from iOS](ios-to-winui.md) +- [WinUI agent plugin](../winui-agent-plugin.md) +- [Windows App SDK migration guide](https://learn.microsoft.com/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/migrate-to-windows-app-sdk-ovw) diff --git a/hub/apps/develop/ai-assisted/quickstart.md b/hub/apps/develop/ai-assisted/quickstart.md new file mode 100644 index 0000000000..f062a01a2e --- /dev/null +++ b/hub/apps/develop/ai-assisted/quickstart.md @@ -0,0 +1,185 @@ +--- +title: "Quickstart: Build and publish a Windows app with AI" +description: Go from zero to a published Windows app in under 30 minutes using free tools — VS Code, the WinUI agent plugin for GitHub Copilot, dotnet new templates, and the Windows App Development CLI. +ms.topic: quickstart +ms.date: 05/13/2026 +ms.author: jken +author: GrantMeStrength +--- + +# Quickstart: Build and publish a Windows app with AI + +In this quickstart you go from an empty folder to a published Windows app using AI assistance throughout. No Visual Studio required. + +> [!div class="checklist"] +> * Install the required free tools (~5 minutes) +> * Scaffold a WinUI app from the command line +> * Use the `winui-dev` AI agent to add features +> * Package and publish to the Microsoft Store + +**Time to complete:** approximately 30 minutes +**Cost:** free (GitHub Copilot free tier is sufficient) + +--- + +## Prerequisites + +Install the following tools before you start. All are free. + +**1. Visual Studio Code** + +```powershell +winget install Microsoft.VisualStudioCode +``` + +**2. .NET SDK 10 or later** + +```powershell +winget install Microsoft.DotNet.SDK.10 +``` + +**3. Windows App Development CLI (winapp CLI)** + +```powershell +winget install Microsoft.winappcli --source winget +``` + +**4. WinUI dotnet new templates** + +```powershell +dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates +``` + +**5. GitHub Copilot CLI** (requires a [GitHub Copilot subscription](https://github.com/features/copilot) — free tier available) + +```powershell +winget install GitHub.cli +``` + +> [!IMPORTANT] +> Close and reopen your terminal after the install completes. The `gh` command won't be available until a new shell session picks up the updated PATH. + +```powershell +gh auth login +gh extension install github/gh-copilot +``` + +**6. WinUI agent plugin for GitHub Copilot** + +```powershell +gh copilot plugin install winui@awesome-copilot +``` + +**7. WinApp extension for VS Code** + +```powershell +code --install-extension microsoft-winappcli.winapp +``` + +Or search **WinApp** in the Extensions panel (**Ctrl+Shift+X**). See [VS Code tools](vs-code-tools.md) for a full command reference. + +**Verify your setup** + +```powershell +winapp --version +``` + +> [!TIP] +> For best results, also connect your AI agent to the [Microsoft Learn MCP server](vs-code-tools.md#microsoft-learn-mcp-server) — it fetches current WinUI 3 API docs at query time rather than relying on training data. + +--- + +## Step 1: Scaffold a new WinUI app + +Create a new folder and scaffold a WinUI app with a NavigationView layout: + +```powershell +mkdir MyFirstApp +cd MyFirstApp +dotnet new winui-navview +``` + +--- + +## Step 2: Run the app + +Build and run the app to confirm everything is working before you start adding features: + +```powershell +dotnet run +``` + +The app launches as a loose-layout package — no MSIX install required. You should see a WinUI 3 app with a NavigationView containing Home, About, and Settings pages: + +:::image type="content" source="images/myfirstapp.png" alt-text="Screenshot of MyFirstApp running — a WinUI 3 window with a NavigationView showing Home, About, and Settings items, with the Home page selected displaying 'This is the Home page'."::: + +Once it launches successfully, open the project in VS Code: + +```powershell +code . +``` + +> [!NOTE] +> Don't press **F5** before the first successful `dotnet run`. VS Code's debugger looks for an `.exe` that doesn't exist yet. After `dotnet run` succeeds, F5 and the **Run** button in the WinApp extension panel both work normally. + +--- + +## Step 3: Use the AI agent to add a feature + +In VS Code, open GitHub Copilot Chat (**Ctrl+Alt+I**), switch to **Agent mode**, and select the **winui-dev** agent. Type a request such as: + +``` +Add a settings page to my WinUI NavigationView app with a toggle for dark mode +``` + +The agent generates the code, creates any required files, and updates your navigation structure. Review the changes, then verify the result: + +```powershell +dotnet run +``` + +Navigate to the Settings page in the running app to confirm the feature was added correctly. + +> [!TIP] +> Want to automate UI verification? See [Testing WinUI apps](testing.md) for `winapp ui` commands that inspect, search, and screenshot your app's UI tree — useful for CI pipelines. + +--- + +## Step 4: Package the app + +Publish your app to a folder, then package it as an MSIX installer. + +> [!IMPORTANT] +> The packaging step installs a certificate to your machine's trusted root store and requires an **elevated (Administrator) terminal**. Right-click PowerShell or Windows Terminal and select **Run as administrator**, then navigate back to your project folder. + +```powershell +dotnet publish -o ./publish +winapp pack ./publish --generate-cert --install-cert +``` + +`--generate-cert --install-cert` creates and installs a local development certificate for testing. For Store submission, use your Partner Center certificate instead. + +--- + +## Step 5: Publish to the Microsoft Store + +Submit your app directly from the command line: + +```powershell +winapp store publish ./*.msix --appId +``` + +> [!NOTE] +> Publishing requires a [Partner Center account](https://partner.microsoft.com/dashboard). App certification typically takes 1–3 business days. + +--- + +## Next steps + +You've built and published a Windows app using only free tools and AI assistance. Here's where to go next: + +- **Go deeper on AI**: [WinUI agent plugin](winui-agent-plugin.md) — learn all 8 skills and when to use each +- **Use VS Code fully**: [VS Code tools](vs-code-tools.md) — run, debug, package, and sign without the terminal +- **Have an existing app?**: [Migrate from WPF](migrate/wpf-to-winui.md) or [migrate from UWP](migrate/uwp-to-winui.md) with AI assistance +- **Write better tests**: [AI-assisted testing](testing.md) — generate and automate UI tests +- **Understand the risks**: [Security and responsible AI](security-and-responsible-ai.md) — what to review before shipping AI-generated code diff --git a/hub/apps/develop/ai-assisted/security-and-responsible-ai.md b/hub/apps/develop/ai-assisted/security-and-responsible-ai.md new file mode 100644 index 0000000000..600860aa71 --- /dev/null +++ b/hub/apps/develop/ai-assisted/security-and-responsible-ai.md @@ -0,0 +1,158 @@ +--- +title: "Security and responsible AI for Windows development" +description: Guidance on reviewing AI-generated code for security risks, using AI tools responsibly, and shipping safe Windows apps that incorporate AI features. +ms.topic: overview +ms.date: 05/13/2026 +ms.author: jken +author: GrantMeStrength +--- + +# Security and responsible AI for Windows development + +AI tools can dramatically accelerate Windows app development — but speed doesn't remove responsibility. The code your AI agent generates is code you ship, and you are accountable for everything in your app regardless of how it was written. + +This page covers two related topics: responsible practices for *using* AI tools to build apps, and security issues specific to AI-generated code. + +## You own the code + +When an AI agent generates a function, a layout, or an API call, it becomes your code the moment you commit it. The same standards apply whether code was written by hand or generated: + +- Read and understand every change before accepting it +- Test AI-generated code at least as thoroughly as hand-written code — models can generate plausible-looking code that is subtly wrong +- Don't use "the AI wrote it" as an explanation for a bug or a security issue in production + +AI tools don't remove the need for code review. They change what you're reviewing, not whether you review. + +## What not to send to AI tools + +Be deliberate about what you include in prompts and context windows: + +- **Secrets and credentials** — Never paste API keys, passwords, or connection strings into a prompt. Even in a private chat session, credentials in prompts are a security risk and may appear in logs. See [Credential and secret handling](#credential-and-secret-handling) below. +- **Customer data and PII** — Don't use real customer names, emails, or usage data as example inputs, even to explain a bug. Use synthetic data. +- **Proprietary business logic** — Understand your organisation's policy on what source code can be sent to external AI services before sharing internal systems code. + +## Input validation + +AI tends to generate permissive input handling. Always validate lengths, types, and ranges before acting on user input. + +- Never pass raw `TextBox.Text` values to shell commands, file paths, or database queries. +- Validate string lengths before writing to storage or sending over the network. +- Use an allow-list approach for file paths — check that resolved paths stay within expected directories. + +Add this to your prompt: *"Add input validation and length limits to all user-facing fields."* + +## Credential and secret handling + +Never hardcode API keys, passwords, or connection strings. AI often generates placeholder strings like `"your-api-key-here"` — treat these as bugs. + +- Store credentials in `Windows.Security.Credentials.PasswordVault`: + + ```csharp + var vault = new PasswordVault(); + vault.Add(new PasswordCredential("MyApp", username, password)); + ``` + +- Retrieve them at runtime: + + ```csharp + var credential = vault.Retrieve("MyApp", username); + credential.RetrievePassword(); + ``` + +- Use environment variables or Azure Key Vault for service credentials in server-side or CI scenarios. + +## Package and dependency integrity + +Review every NuGet package an AI agent suggests before adding it to your project. + +- Verify the publisher on [nuget.org](https://www.nuget.org/) — look for the blue shield (Microsoft) or a known publisher. +- Scan for known vulnerabilities: + ```powershell + dotnet list package --vulnerable + ``` +- Prefer packages with recent updates and active maintenance. + +## App capabilities and permissions + +AI-generated `Package.appxmanifest` files often include broad capabilities. Review the `` section and remove anything your app doesn't need. + +Common over-broad capabilities to watch for: +- `broadFileSystemAccess` — only needed if your app genuinely reads arbitrary file system paths +- `documentsLibrary` — requires Store special approval; avoid unless necessary +- `userAccountInformation` — only if you need the user's name or photo + +## Code review checklist + +Before shipping AI-generated code, verify: + +- No hardcoded secrets or credentials +- User input validated before use +- File paths checked against allowed directories +- Minimum necessary capabilities declared in the manifest +- NuGet packages scanned for vulnerabilities (`dotnet list package --vulnerable`) +- Sensitive data stored in `PasswordVault`, not `ApplicationData.LocalSettings` +- All network calls use HTTPS +- Exception messages don't expose internal paths or stack traces to users + +## AI models have stale knowledge + +The AI tools you use today were trained on data with a cutoff date. For Windows development, this means models have seen far more UWP samples than WinUI 3 samples — which is exactly why this documentation section exists. + +Don't treat AI output as authoritative for: + +- Current API names and namespaces (verify against [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/)) +- Current SDK versions and package names +- Store policies and submission requirements (these change frequently) +- Security guidance (models may reproduce outdated cryptography or auth patterns) + +The [Microsoft Learn MCP server](vs-code-tools.md#microsoft-learn-mcp-server) and [WinUI agent plugin](winui-agent-plugin.md) mitigate stale knowledge by grounding your agent in current documentation — but always verify anything security-critical against primary sources. + +## Accessibility + +AI-generated UI frequently omits accessibility support. A model trained on millions of XAML samples will reproduce the average quality of those samples — and the average historically skips `AutomationProperties`, keyboard navigation, and sufficient contrast. + +When accepting AI-generated XAML or controls code: + +- Check that interactive elements have `AutomationProperties.AutomationId` and `AutomationProperties.Name` set +- Verify focus order is logical — tab stops should follow reading order +- Test with Narrator or another screen reader before shipping +- Use the [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/) tool to catch gaps automatically + +Ask your agent explicitly: *"Add accessibility properties to all interactive elements in this XAML."* Don't assume it was done. + +## If your app uses AI features + +If you're building AI capabilities *into* your app — not just using AI to write the app — additional responsibilities apply. + +**Be transparent with users.** Tell users: +- What data your app sends to AI services +- Whether AI is making decisions that affect them +- How to opt out if appropriate + +**Keep humans in the loop for consequential actions.** Don't let AI autonomously delete data, make purchases, send messages on behalf of the user, or take other irreversible actions without explicit confirmation. + +**Test for bias and unexpected outputs.** AI models can produce outputs that are biased, offensive, or factually wrong. Test your app's AI features with diverse inputs and edge cases before shipping. + +**Use content safety tools.** If your app generates or processes user-facing text, images, or other content using AI, use [Azure AI Content Safety](https://learn.microsoft.com/azure/ai-services/content-safety/overview) or equivalent filtering to catch harmful outputs before they reach users. + +## Licensing and attribution + +AI tools may generate code that resembles existing open-source code. Before using AI-generated code in a commercial app: + +- Know your organisation's policy on AI-generated code contributions +- Review Microsoft's [guidance on Copilot and intellectual property](https://learn.microsoft.com/legal/cognitive-services/openai/transparency-note) +- Apply the same open-source license compliance checks you would to any third-party code + +## Microsoft's Responsible AI principles + +Microsoft designs AI products and features guided by six principles: fairness, reliability and safety, privacy and security, inclusiveness, transparency, and accountability. + +Learn more at [microsoft.com/ai/responsible-ai](https://www.microsoft.com/en-us/ai/responsible-ai). + +## Related content + +- [Microsoft Security Response Center](https://msrc.microsoft.com/) +- [Microsoft Responsible AI principles](https://www.microsoft.com/en-us/ai/responsible-ai) +- [Azure AI Content Safety](https://learn.microsoft.com/azure/ai-services/content-safety/overview) +- [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/) +- [Microsoft Copilot transparency note](https://learn.microsoft.com/legal/cognitive-services/openai/transparency-note) diff --git a/hub/apps/develop/ai-assisted/testing.md b/hub/apps/develop/ai-assisted/testing.md new file mode 100644 index 0000000000..5a9e0ef890 --- /dev/null +++ b/hub/apps/develop/ai-assisted/testing.md @@ -0,0 +1,70 @@ +--- +title: "AI-assisted testing for Windows apps" +description: Use the winui-ui-testing skill and winapp ui commands to automate UI inspection and testing of your WinUI 3 app. +ms.topic: overview +ms.date: 05/13/2026 +ms.author: jken +author: GrantMeStrength +--- + +# AI-assisted testing for Windows apps + +The `winapp ui` commands and `winui-ui-testing` skill let your AI agent inspect, interact with, and validate your app's UI automatically — describing what it sees in natural language so you can iterate without writing test harness code first. + +## UI inspection commands + +The `winui-ui-testing` skill is included in the `winui@awesome-copilot` plugin. If you installed the plugin during [setup](quickstart.md#prerequisites), no additional install is required. + +| Command | What it does | +|---------|-------------| +| `winapp ui inspect` | Dumps the accessibility tree of the running app | +| `winapp ui screenshot` | Captures a screenshot of the app window | +| `winapp ui click ` | Clicks a button or selects an item | +| `winapp ui invoke ` | Invokes the default action on a control | +| `winapp ui search ` | Searches the element tree by name or AutomationId | +| `winapp ui set-value ` | Sets the value of a TextBox or ComboBox | + +## Ask your agent to test the app + +1. Run the app: + ```powershell + dotnet run + ``` +2. Ask your agent a natural-language question, such as: + > "Look at the running app and tell me if the Save button is reachable when the form is empty." +3. The agent uses `winapp ui inspect` and `winapp ui screenshot` to examine the app and respond. + +This workflow lets you catch issues — missing keyboard focus, disabled controls, layout problems — before writing a single line of test code. + +## Write automated tests + +Once you've explored the app interactively, ask your agent to generate formal tests. Use this starter prompt: + +```text +Write an xUnit UI test for my WinUI 3 app that: +1. Launches the app with dotnet run +2. Verifies the main window title is "My App" +3. Clicks the button with AutomationId "SaveButton" +4. Verifies a success message appears +Use the winapp ui commands for element interaction. +``` + +The generated tests use `winapp ui` commands as the interaction layer, so they run without a separate UI automation framework. + +## Set AutomationIds in your XAML + +For `winapp ui click` to target elements reliably, set `AutomationProperties.AutomationId` in your XAML: + +```xml +