Merge pull request #5766 from MicrosoftDocs/main

learn-build-service-prod[bot] · web-flow · commit 28eadf8c1ea3 · 2025-09-02T20:13:17.000Z
Auto Publish – main to live - 2025-09-02 20:11 UTC
diff --git a/hub/apps/get-started/start-here.md b/hub/apps/get-started/start-here.md
@@ -155,7 +155,7 @@ Now your project is using the latest WinUI features that are available, and it's
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Complete a tutorial to create a note app with WinUI](../tutorials/winui-notes/index.yml)
+> [Complete a tutorial to create a note app with WinUI](../tutorials/winui-notes/intro.md)
 
 * To get an idea of what WinUI has to offer, check out the WinUI Gallery app.
   [!INCLUDE [winui-3-gallery](../../includes/winui-3-gallery.md)]
diff --git a/hub/apps/toc.yml b/hub/apps/toc.yml
@@ -16,6 +16,17 @@ items:
             href: get-started/start-here.md
           - name: Build your first app
             href: tutorials/winui-notes/intro.md
+            items:
+              - name: 1 - Project setup
+                href: tutorials/winui-notes/project.md
+              - name: 2 - Note page
+                href: tutorials/winui-notes/note.md
+              - name: 3 - View and model
+                href: tutorials/winui-notes/view-model.md
+              - name: 4 - All notes
+                href: tutorials/winui-notes/all-notes.md
+              - name: 5 - Navigation
+                href: tutorials/winui-notes/navigation.md
           - name: Samples and resources
             href: get-started/samples.md
           - name: Best practices
diff --git a/hub/apps/tutorials/winui-notes/all-notes.md b/hub/apps/tutorials/winui-notes/all-notes.md
@@ -1,12 +1,13 @@
 ---
-title: WinUI Notes 3
-description: WinUI Notes 3
+title: WinUI Notes tutorial - Step 4 - All notes
+description: WinUI Notes - Step 4 - Add a view and model for all notes.
 author: jwmsft
 ms.author: jimwalk
-ms.date: 03/26/2025
+ms.date: 09/02/2025
 ms.topic: tutorial
 no-loc: ["NotePage.xaml", "NotePage.xaml.cs", "Note.cs", "AllNotesPage.xaml", "AllNotes.cs", "WinUI 3 Gallery"]
 ---
+# Add a view and model for all notes
 
 This portion of the tutorial adds a new page to the app, a view that displays all of the notes previously created.
 
@@ -88,12 +89,12 @@ The new data model represents the data required to display multiple notes. Here,
 
 The previous code declares a collection of `Note` items, named `Notes`, and uses the `LoadNotes` method to load notes from the app's local storage.
 
-The `Notes` collection uses an [ObservableCollection](/dotnet/api/system.collections.objectmodel.observablecollection-1), which is a specialized collection that works well with data binding. When a control that lists multiple items, such as an [ItemsView](../../../design/controls/itemsview.md), is bound to an `ObservableCollection`, the two work together to automatically keep the list of items in sync with the collection. If an item is added to the collection, the control is automatically updated with the new item. If an item is added to the list, the collection is updated.
+The `Notes` collection uses an [ObservableCollection](/dotnet/api/system.collections.objectmodel.observablecollection-1), which is a specialized collection that works well with data binding. When a control that lists multiple items, such as an [ItemsView](../../design/controls/itemsview.md), is bound to an `ObservableCollection`, the two work together to automatically keep the list of items in sync with the collection. If an item is added to the collection, the control is automatically updated with the new item. If an item is added to the list, the collection is updated.
 
- :::image type="icon" source="../media/doc-icon-sm.png" border="false"::: Learn more in the docs:
+ :::image type="icon" source="media/doc-icon-sm.png" border="false"::: Learn more in the docs:
 
 - [StorageFolder class](/uwp/api/windows.storage.storagefolder), [StorageFile class](/uwp/api/windows.storage.storagefile), [IStorageItem.IsOfType method](/uwp/api/windows.storage.istorageitem.isoftype)
-- [Access files and folders with Windows App SDK and WinRT APIs](../../../develop/files/winrt-files.md)
+- [Access files and folders with Windows App SDK and WinRT APIs](../../develop/files/winrt-files.md)
 
 Now that the `AllNotes` model is ready to provide data for the view, you need to create an instance of the model in `AllNotesPage` so the view can access the model.
 
@@ -165,7 +166,7 @@ Now that you've created `AllNotesPage`, you need to update `MainWindow.xaml` one
 
 If you run the app now, you'll see that the note you created previously is loaded into the `ItemsView` control. However, it's just shown as the string representation of the object. The `ItemsView` doesn't know how this item should be displayed. You'll correct this in the next section.
 
-:::image type="content" source="../media/all-notes/itemsview-no-template.png" alt-text="The notes app UI with the note list showing the Note class name instead of the note content.":::
+:::image type="content" source="media/all-notes/itemsview-no-template.png" alt-text="The notes app UI with the note list showing the Note class name instead of the note content.":::
 
 ### Add a data template
 
@@ -233,11 +234,11 @@ When you use the `x:Bind` markup extension in a `DataTemplate`, you have to spec
 
 When you run the app, the data template is applied to your `Note` items and looks like this if your Windows Personalization > Colors settings use the Light mode:
 
-:::image type="content" source="../media/all-notes/itemsview-with-template.png" alt-text="The notes app UI with the note list showing the note content and date formatted by a data template.":::
+:::image type="content" source="media/all-notes/itemsview-with-template.png" alt-text="The notes app UI with the note list showing the note content and date formatted by a data template.":::
 
 However, if your Windows Personalization > Colors settings use the Dark mode, it will look like this:
 
-:::image type="content" source="../media/all-notes/itemsview-with-template-dark.png" alt-text="The notes app UI with a dark background but light gray note template.":::
+:::image type="content" source="media/all-notes/itemsview-with-template-dark.png" alt-text="The notes app UI with a dark background but light gray note template.":::
 
 This is not the intended look for the app. It happened because there are hard-coded color values in the data template for the note. By default, WinUI elements adapt to the user's Dark or Light color preference. When you define you own elements, like a data template, you need to be careful to do the same.
 
@@ -286,20 +287,23 @@ WinUI includes a variety of built-in resources that you can use to make your app
 
 Now when you run the app with a Light color setting, it will look like this:
 
-:::image type="content" source="../media/all-notes/itemsview-themed-template.png" alt-text="The notes app UI with a light background and light note template.":::
+:::image type="content" source="media/all-notes/itemsview-themed-template.png" alt-text="The notes app UI with a light background and light note template.":::
 
 And when you run the app with a Dark color setting, it will look like this:
 
-:::image type="content" source="../media/all-notes/itemsview-themed-template-dark.png" alt-text="The notes app UI with a dark background and dark note template.":::
+:::image type="content" source="media/all-notes/itemsview-themed-template-dark.png" alt-text="The notes app UI with a dark background and dark note template.":::
 
-:::image type="icon" source="../media/doc-icon-sm.png" border="false"::: Learn more in the docs:
+:::image type="icon" source="media/doc-icon-sm.png" border="false"::: Learn more in the docs:
 
-- [Item containers and templates](../../../design/controls/item-containers-templates.md)
-- [ResourceDictionary and XAML resource references](../../../develop/platform/xaml/xaml-resource-dictionary.md)
+- [Item containers and templates](../../design/controls/item-containers-templates.md)
+- [ResourceDictionary and XAML resource references](../../develop/platform/xaml/xaml-resource-dictionary.md)
 
 > [!TIP]
 > The WinUI 3 Gallery app is a great way to learn about different WinUI controls and design guidelines. To see the theme resources used in the data template, [open the WinUI 3 Gallery app to the Color guidance](winui3gallery://item/Color). From there, you can see what the resources look like and copy the values you need directly from the app.
 >
 > You can also open the [Typography page](winui3gallery://item/Typography) and [Geometry page](winui3gallery://item/Geometry) to see other built-in resources used in this data template.
 
-[!INCLUDE [winui-3-gallery](../../../../../hub/includes/winui-3-gallery.md)]
+[!INCLUDE [winui-3-gallery](../../../../hub/includes/winui-3-gallery.md)]
+
+> [!div class="nextstepaction"]
+> [Continue to step 5 - Add navigation between pages](navigation.md)
diff --git a/hub/apps/tutorials/winui-notes/intro.md b/hub/apps/tutorials/winui-notes/intro.md
@@ -1,12 +1,13 @@
 ---
-title: WinUI Notes
-description: WinUI Notes
+title: WinUI Notes tutorial - Introduction
+description: WinUI Notes tutorial introduction.
 author: jwmsft
 ms.author: jimwalk
-ms.date: 03/26/2025
+ms.date: 09/02/2025
 ms.topic: tutorial
 ms.localizationpriority: medium
 ---
+# Create a WinUI app
 
 This tutorial series demonstrates how to create a WinUI 3 app using XAML and C#. The app you'll create is a note app, where the user can create, save, and load multiple notes. You can download or view the code for this tutorial from the [GitHub repo](https://github.com/MicrosoftDocs/windows-topic-specific-samples/tree/winui-3/tutorials/winui-notes).
 
@@ -30,11 +31,11 @@ The final application is shown below:
 
 _AllNotesPage_
 
-:::image type="content" border="false" source="../media/intro/final-all-notes.png" alt-text="Final screenshot of the notes app, showing three save notes.":::
+:::image type="content" border="false" source="media/intro/final-all-notes.png" alt-text="Final screenshot of the notes app, showing three save notes.":::
 
 _NotePage_
 
-:::image type="content" border="false" source="../media/intro/final-note.png" alt-text="Final screenshot of the notes app, showing a new blank note.":::
+:::image type="content" border="false" source="media/intro/final-note.png" alt-text="Final screenshot of the notes app, showing a new blank note.":::
 
 ## Create the Visual Studio project
 
@@ -49,11 +50,14 @@ To begin this tutorial, you must create a WinUI 3 app project in Visual Studio u
   This tutorial uses features that are new in Windows App SDK 1.7. You must make sure the Windows App SDK NuGet package is updated to version 1.7 or later.  
 
 > [!IMPORTANT]
-> If you have not created a WinUI 3 project before, follow the steps in **[Start developing Windows apps](../../../get-started/start-here.md)** to make sure your dev environment and Visual Studio project are set up correctly.
+> If you have not created a WinUI 3 project before, follow the steps in **[Start developing Windows apps](../../get-started/start-here.md)** to make sure your dev environment and Visual Studio project are set up correctly.
 
-When you run your blank app project (as outlined in [Start developing Windows apps](../../../get-started/start-here.md)), you should see an empty window that looks like this:
+When you run your blank app project (as outlined in [Start developing Windows apps](../../get-started/start-here.md)), you should see an empty window that looks like this:
 
-:::image type="content" source="../media/intro/step-0.png" alt-text="The notes app window with a title bar and empty content area.":::
+:::image type="content" source="media/intro/step-0.png" alt-text="The notes app window with a title bar and empty content area.":::
 
 > [!TIP]
 > You'll frequently refer to API reference docs and conceptual docs while building Windows apps. In this tutorial, you'll see links inline in the text, and in groups labeled, "Learn more in the docs:". These links are optional; you don't need to follow them to complete the tutorial. They're provided in case you want to make note of where to find the information you'll need when you start to create your own apps.
+
+> [!div class="nextstepaction"]
+> [Continue to step 1 - Project setup](project.md)
diff --git a/hub/apps/tutorials/winui-notes/navigation.md b/hub/apps/tutorials/winui-notes/navigation.md
@@ -1,11 +1,12 @@
 ---
-title: WinUI Notes 5
-description: WinUI Notes 5
+title: WinUI Notes -Step 5 - Navigation
+description: WinUI Notes - Step 5 - Add navigation between pages
 author: jwmsft
 ms.author: jimwalk
 ms.date: 09/02/2025
 ms.topic: tutorial
 ---
+# Navigate between pages
 
 This portion of the tutorial adds the final piece to the app, navigation between the _all notes_ page and the individual _note_ page.
 
@@ -189,10 +190,19 @@ Next, you need to update the code in `NotePage` to navigate back after the note
 
 Now you can run your app. Try adding new notes, navigating back and forth between notes, and deleting notes.
 
-:::image type="icon" source="../media/doc-icon-sm.png" border="false"::: Learn more in the docs:
+:::image type="icon" source="media/doc-icon-sm.png" border="false"::: Learn more in the docs:
 
-- [Implement navigation between two pages](../../../design/basics/navigate-between-two-pages.md)
-- [Navigation history and backwards navigation](../../../design/basics/navigation-history-and-backwards-navigation.md)
+- [Implement navigation between two pages](../../design/basics/navigate-between-two-pages.md)
+- [Navigation history and backwards navigation](../../design/basics/navigation-history-and-backwards-navigation.md)
 - [Frame class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.frame), [Page class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.page)
 
+## Next steps
 
+Congratulations! You've completed the _Create a WinUI app_ tutorial!
+
+The following links provide more information about creating apps with WinUI and the Windows App SDK:
+
+- [Samples and resources](/windows/apps/get-started/samples)
+- [Design for Windows apps](/windows/apps/design/)
+- [Develop Windows desktop apps](/windows/apps/develop/)
+- [Controls for Windows apps](/windows/apps/design/controls/)
diff --git a/hub/apps/tutorials/winui-notes/note.md b/hub/apps/tutorials/winui-notes/note.md
@@ -1,12 +1,13 @@
 ---
-title: WinUI Notes 2
-description: WinUI Notes 2
+title: WinUI Notes tutorial - Step 2 - Note page
+description: WinUI Notes tutorial - Step 2 - Create a page for a note.
 author: jwmsft
 ms.author: jimwalk
-ms.date: 03/26/2025
+ms.date: 09/02/2025
 ms.topic: tutorial
 no-loc: ["App.xaml", "App.xaml.cs", "MainWindow.xaml", "MainWindow.xaml.cs", "NotePage.xaml", "NotePage.xaml.cs"]
 ---
+# Create a page for a note
 
 Now you'll create a page that allows a user to edit a note, and then you'll write the code to save or delete the note.
 
@@ -68,7 +69,7 @@ First, add the new page to the project:
 
 Let's break down the key parts of the XAML controls placed on the page:
 
-:::image type="content" source="../media/note/app-layout.png" alt-text="The new note page UI with the grid highlighted by Visual Studio.":::
+:::image type="content" source="media/note/app-layout.png" alt-text="The new note page UI with the grid highlighted by Visual Studio.":::
 
 - The [Grid.RowDefinitions](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.grid.rowdefinitions) and [Grid.ColumnDefinitions](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.grid.columndefinitions) define a grid with 2 rows and 3 columns (placed below the title bar).
   - The bottom row is automatically (`Auto`) sized to fit its content, the two buttons. The top row uses all the remaining vertical space (`*`).
@@ -86,10 +87,10 @@ Let's break down the key parts of the XAML controls placed on the page:
 
 - Two `<Button>` controls are inside the `<StackPanel>` and arranged horizontally. You'll add the code to handle the buttons' [Click](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.primitives.buttonbase.click) events in the next section.
 
- :::image type="icon" source="../media/doc-icon-sm.png" border="false"::: Learn more in the docs:
+ :::image type="icon" source="media/doc-icon-sm.png" border="false"::: Learn more in the docs:
 
-- [Responsive layouts with XAML](../../../design/layout/layouts-with-xaml.md)
-- [Layout panels](../../../design/layout/layout-panels.md)
+- [Responsive layouts with XAML](../../design/layout/layouts-with-xaml.md)
+- [Layout panels](../../design/layout/layout-panels.md)
 - [XAML namespaces and namespace mapping](/windows/uwp/xaml-platform/xaml-namespaces-and-namespace-mapping)
 
 ## Load and save a note
@@ -153,7 +154,7 @@ Now you're going to add code to the **NotePage.xaml.cs** code-behind file to han
     > [!IMPORTANT]
     > You need to mark this method with the `async` keyword because the file access calls are asynchronous. In short, if you call a method that ends in `...Async` (like `TryGetItemAsync`), you can add the [await](/dotnet/csharp/language-reference/operators/await) operator to the call. This keeps subsequent code from executing until the awaited call completes and keeps your UI responsive. When you use `await`, the method that you're calling from needs to be marked with the [async](/dotnet/csharp/language-reference/keywords/async) keyword. For more info, see [Call asynchronous APIs in C#](/windows/uwp/threading-async/call-asynchronous-apis-in-csharp-or-visual-basic).
 
- :::image type="icon" source="../media/doc-icon-sm.png" border="false"::: Learn more in the docs:
+ :::image type="icon" source="media/doc-icon-sm.png" border="false"::: Learn more in the docs:
 
 - [Access files and folders with WinRT APIs](/windows/apps/develop/files/winrt-files)
 - [Call asynchronous APIs in C#](/windows/uwp/threading-async/call-asynchronous-apis-in-csharp-or-visual-basic)
@@ -164,7 +165,7 @@ Next, add the [Click](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.contr
 
 1. In the **NotePage.xaml** file, place your cursor after the `Content` attribute in the **Save** `Button` control. Type `Click=`. At this point, Visual Studio should pop up an auto-complete UI that looks like this:
 
-    :::image type="content" source="../media/note/new-event-xaml.png" alt-text="A screenshot of the Visual Studio new event handler auto complete UI in the XAML editor":::
+    :::image type="content" source="media/note/new-event-xaml.png" alt-text="A screenshot of the Visual Studio new event handler auto complete UI in the XAML editor":::
 
     - Press the down-arrow key to select **\<New Event Handler>**, then press <kbd>Tab</kbd>. Visual Studio will complete the attribute with `Click="Button_Click"` and add an event handler method named `Button_Click` in the **NotePage.xaml.cs** code-behind file.
 
@@ -182,12 +183,12 @@ Next, add the [Click](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.contr
     > [!TIP]
     > To locate code in your app, click **Search** in the Visual  Studio title bar and use the **Code Search** option. Double-click the search result to open the code in the code editor.
     >
-    > :::image type="content" source="../media/note/vs-code-search.png" alt-text="Search feature in Visual Studio":::
+    > :::image type="content" source="media/note/vs-code-search.png" alt-text="Search feature in Visual Studio":::
 
 1. Place your cursor before the "B" in `Button` and type `Save`. Wait a moment, and the method name will be highlighted in green.
 1. When you hover over the method name, Visual Studio will show a tooltip with a screwdriver or lightbulb icon. Click the down-arrow button next to the icon, then click **Rename 'Button_Click' to 'SaveButton_Click**'.
 
-    :::image type="content" source="../media/note/method-rename.png" alt-text="The Visual Studio method rename popup UI.":::
+    :::image type="content" source="media/note/method-rename.png" alt-text="The Visual Studio method rename popup UI.":::
 
     Visual Studio will rename the method everywhere in your app, including in the XAML file where you first added it to the `Button`.
 1. Repeat these steps for the **Delete** button, and rename the method to `DeleteButton_Click`.
@@ -294,3 +295,6 @@ With this code in place, you can test the app to make sure the note saves and lo
 
 > [!IMPORTANT]
 > After you've confirmed that saving and deleting a note works correctly, create and save a new note again. You'll want to have a saved note to test the app in later steps.
+
+> [!div class="nextstepaction"]
+> [Continue to step 3 - Add a view and model for the note](view-model.md)
diff --git a/hub/apps/tutorials/winui-notes/project.md b/hub/apps/tutorials/winui-notes/project.md
diff --git a/hub/apps/tutorials/winui-notes/view-model.md b/hub/apps/tutorials/winui-notes/view-model.md
