|
| 1 | +--- |
| 2 | +title: "Tutorial: Build a Windows app with GitHub Copilot" |
| 3 | +description: A step-by-step tutorial for building a WinUI 3 Windows app using GitHub Copilot, the WinUI 3 plugin, and the Microsoft Learn MCP server. |
| 4 | +ms.topic: tutorial |
| 5 | +ms.date: 03/10/2026 |
| 6 | +ms.author: jken |
| 7 | +author: GrantMeStrength |
| 8 | +keywords: windows, github copilot, winui, tutorial, agent mode, mcp server |
| 9 | +ms.localizationpriority: medium |
| 10 | +--- |
| 11 | + |
| 12 | +# Tutorial: Build a Windows app with GitHub Copilot |
| 13 | + |
| 14 | +In this tutorial, you use GitHub Copilot in agent mode to build a complete WinUI 3 app — a simple **notes app** with a list of notes, the ability to add and delete entries, and a settings page. You'll see exactly which prompts to use at each step, and how the WinUI 3 plugin and Learn MCP Server keep Copilot accurate throughout. |
| 15 | + |
| 16 | +> [!div class="checklist"] |
| 17 | +> * Scaffold a WinUI 3 project with Copilot |
| 18 | +> * Generate a XAML UI with Copilot |
| 19 | +> * Add business logic with Copilot |
| 20 | +> * Add a Windows notification using the Learn MCP Server |
| 21 | +> * Package the app with winapp CLI |
| 22 | +
|
| 23 | +## Prerequisites |
| 24 | + |
| 25 | +- GitHub Copilot set up with the WinUI 3 plugin and Learn MCP Server — see [Set up GitHub Copilot for Windows development](ai-setup.md) |
| 26 | +- [Visual Studio 2022](/visualstudio/install/install-visual-studio) with the **WinUI application development** workload |
| 27 | +- [winapp CLI](../dev-tools/winapp-cli/index.md) installed (`winget install Microsoft.winappcli`) |
| 28 | + |
| 29 | +--- |
| 30 | + |
| 31 | +## Part 1: Scaffold the project |
| 32 | + |
| 33 | +### Create the WinUI project |
| 34 | + |
| 35 | +Create a new WinUI 3 project: in Visual Studio, select **File** > **New** > **Project**, filter by **WinUI**, and choose the **Blank App (Packaged)** C# template. Name the project `NotesApp` and open it. |
| 36 | + |
| 37 | +### Open Copilot agent mode and scaffold the structure |
| 38 | + |
| 39 | +Open the Copilot Chat panel in Visual Studio and switch to **agent mode**. Then enter: |
| 40 | + |
| 41 | +> *"I have a new blank WinUI 3 project called NotesApp. Set up an MVVM architecture with the following structure: a MainWindow with a NavigationView, three pages (Notes, Favorites, Settings), a ViewModels folder with a base ViewModel class and a NotesViewModel, and a Models folder with a Note model that has Id, Title, Content, and CreatedAt properties. Use CommunityToolkit.Mvvm."* |
| 42 | +
|
| 43 | +Copilot will create the folder structure, add the CommunityToolkit.Mvvm NuGet package reference, generate the base classes, and wire up the NavigationView. Review the output — if anything looks wrong, ask Copilot to correct it in the same chat session. |
| 44 | + |
| 45 | +> [!TIP] |
| 46 | +> If Copilot generates `Windows.UI.Xaml` namespaces instead of `Microsoft.UI.Xaml`, the WinUI 3 plugin's custom instructions should catch this. If you see it, prompt: *"Fix any instances of Windows.UI.Xaml — this is a WinUI 3 project, so all XAML namespaces should use Microsoft.UI.Xaml."* |
| 47 | +
|
| 48 | +--- |
| 49 | + |
| 50 | +## Part 2: Build the UI |
| 51 | + |
| 52 | +### Generate the Notes page |
| 53 | + |
| 54 | +> *"Generate the XAML for the Notes page. It should have a ListView showing notes with Title and a truncated Content preview, a TextBox and Button at the bottom to add a new note, and a Delete button on each item. Bind it to the NotesViewModel. Use WinUI 3 controls and Fluent Design spacing."* |
| 55 | +
|
| 56 | +Copilot generates the XAML, bound to your ViewModel. Ask it to adjust styling or layout as needed — for example: |
| 57 | + |
| 58 | +> *"Make the list items use a card style with a subtle shadow, similar to WinUI Gallery's card examples."* |
| 59 | +
|
| 60 | +### Generate the Settings page |
| 61 | + |
| 62 | +> *"Generate a Settings page with a toggle for dark/light theme and a 'Clear all notes' button with a confirmation dialog. Use ContentDialog for the confirmation — not MessageDialog."* |
| 63 | +
|
| 64 | +The WinUI 3 plugin's instructions steer Copilot toward `ContentDialog` (the correct WinUI 3 approach) and away from the deprecated `MessageDialog`. |
| 65 | + |
| 66 | +--- |
| 67 | + |
| 68 | +## Part 3: Add business logic |
| 69 | + |
| 70 | +### Implement note persistence |
| 71 | + |
| 72 | +> *"Implement note persistence in NotesViewModel using System.Text.Json to serialize and deserialize the notes collection to a file in ApplicationData.Current.LocalFolder. Load notes on startup and save whenever the collection changes."* |
| 73 | +
|
| 74 | +Copilot generates the load/save logic. Ask it to add error handling: |
| 75 | + |
| 76 | +> *"Add try/catch around the file operations and log errors to the Debug output."* |
| 77 | +
|
| 78 | +### Implement theme switching |
| 79 | + |
| 80 | +> *"Implement the theme toggle in SettingsViewModel. When the toggle changes, update the RequestedTheme on the application's main window using the correct WinUI 3 approach."* |
| 81 | +
|
| 82 | +--- |
| 83 | + |
| 84 | +## Part 4: Add a Windows notification |
| 85 | + |
| 86 | +Package identity is required for Windows notifications. First, set it up with winapp CLI: |
| 87 | + |
| 88 | +```bash |
| 89 | +winapp create-debug-identity --publisher "CN=NotesApp" |
| 90 | +``` |
| 91 | + |
| 92 | +Now ask Copilot to add a notification that fires when a note is saved: |
| 93 | + |
| 94 | +> *"Add a Windows app notification that shows 'Note saved' with the note title as a subtitle when a note is successfully persisted to disk. Use the Windows App SDK AppNotificationManager."* |
| 95 | +
|
| 96 | +With the Learn MCP Server connected, Copilot can look up the current `AppNotificationBuilder` API and generate correct notification code. It should produce something like: |
| 97 | + |
| 98 | +```csharp |
| 99 | +var notification = new AppNotificationBuilder() |
| 100 | + .AddText("Note saved") |
| 101 | + .AddText(note.Title) |
| 102 | + .BuildNotification(); |
| 103 | +AppNotificationManager.Default.Show(notification); |
| 104 | +``` |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +## Part 5: Package the app |
| 109 | + |
| 110 | +When you're ready to distribute or publish to the Microsoft Store, build a proper MSIX package: |
| 111 | + |
| 112 | +```bash |
| 113 | +winapp pack --output ./publish |
| 114 | +``` |
| 115 | + |
| 116 | +This generates a signed MSIX package ready for sideloading or Store submission. Ask Copilot for help updating the package manifest: |
| 117 | + |
| 118 | +> *"Show me how to update the Package.appxmanifest to set the display name, description, and publisher for Store submission."* |
| 119 | +
|
| 120 | +--- |
| 121 | + |
| 122 | +## Summary |
| 123 | + |
| 124 | +You've built a complete WinUI 3 notes app using: |
| 125 | + |
| 126 | +- **Copilot agent mode** for scaffolding, UI generation, and business logic |
| 127 | +- **WinUI 3 plugin** to keep Copilot on modern, correct APIs throughout |
| 128 | +- **Learn MCP Server** to look up Windows App SDK notification APIs |
| 129 | +- **winapp CLI** for package identity and MSIX packaging |
| 130 | + |
| 131 | +--- |
| 132 | + |
| 133 | +## Optional: Add on-device AI to your app |
| 134 | + |
| 135 | +The notes app is fully functional — but you can take it further by adding an AI feature that runs entirely on the user's device. [Foundry Local](https://learn.microsoft.com/windows/ai/foundry-local/get-started) makes this straightforward: it runs a language model locally and exposes an OpenAI-compatible API. |
| 136 | + |
| 137 | +### Install Foundry Local and download a model |
| 138 | + |
| 139 | +```bash |
| 140 | +winget install Microsoft.AIFoundry.Local |
| 141 | +foundry model run phi-4-mini |
| 142 | +``` |
| 143 | + |
| 144 | +Once the model starts, it listens at `http://localhost:5272/openai/v1`. |
| 145 | + |
| 146 | +### Add the NuGet package |
| 147 | + |
| 148 | +```bash |
| 149 | +dotnet add package Azure.AI.OpenAI |
| 150 | +``` |
| 151 | + |
| 152 | +### Add a "Summarize" button to the Notes page |
| 153 | + |
| 154 | +Ask Copilot: |
| 155 | + |
| 156 | +> *"Add a 'Summarize' button to the Notes page. When clicked, it should send the selected note's content to a local AI endpoint at http://localhost:5272/openai/v1 using the Azure.AI.OpenAI package, and display the summary in a ContentDialog. Model name is phi-4-mini."* |
| 157 | +
|
| 158 | +Copilot generates the `AzureOpenAIClient` call and dialog — the OpenAI-compatible API means the code looks identical to a cloud API call, just pointed at localhost: |
| 159 | + |
| 160 | +```csharp |
| 161 | +var client = new AzureOpenAIClient( |
| 162 | + new Uri("http://localhost:5272/openai/v1"), |
| 163 | + new ApiKeyCredential("foundry-local")); |
| 164 | + |
| 165 | +var completion = await client.GetChatClient("phi-4-mini") |
| 166 | + .CompleteChatAsync($"Summarize this note in 2 sentences: {note.Content}"); |
| 167 | +``` |
| 168 | + |
| 169 | +### What the user sees |
| 170 | + |
| 171 | +No internet connection required. No API key. The model runs on their PC — fast, private, and free. |
| 172 | + |
| 173 | +> [!TIP] |
| 174 | +> For apps targeting Copilot+ PCs, you can swap Foundry Local for [Phi Silica](https://learn.microsoft.com/windows/ai/apis/phi-silica) to use the NPU directly for even faster inference. The API surface is different (Windows AI APIs rather than OpenAI-compatible), but Copilot can help you make the switch. |
| 175 | +
|
| 176 | +--- |
| 177 | + |
| 178 | +> [!div class="nextstepaction"] |
| 179 | +> [Modernize or port a Windows app with Copilot](../windows-app-sdk/migrate-to-windows-app-sdk/ai-modernize.md) |
| 180 | +
|
| 181 | +- [Agentic AI tools for Windows development](../dev-tools/agentic-tools.md) |
| 182 | +- [Foundry Local overview](/windows/ai/foundry-local/get-started) — run any model locally on Windows |
| 183 | +- [Phi Silica](/windows/ai/apis/phi-silica) — NPU-accelerated inference on Copilot+ PCs |
| 184 | +- [Windows AI APIs overview](/windows/ai/) |
| 185 | +- [Windows App Development CLI (winapp CLI)](../dev-tools/winapp-cli/index.md) |
| 186 | +- [Windows App SDK documentation](../windows-app-sdk/index.md) |
0 commit comments