Merge pull request #6658 from MicrosoftDocs/main

Auto Publish – main to live - 2026-04-18 05:00 UTC

Author: learn-build-service-prod[bot]

.openpublishing.redirection.json

@@ -1,5 +1,15 @@
 {
   "redirections": [
+    {
+      "source_path": "hub/apps/publish/partner-center/account-types-locations-and-fees.md",
+      "redirect_url": "/windows/apps/publish/partner-center/open-a-developer-account",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "hub/apps/publish/partner-center/partner-center-developer-account.md",
+      "redirect_url": "/windows/apps/publish/partner-center/open-a-developer-account",
+      "redirect_document_id": false
+    },
     {
       "source_path": "hub/apps/design/widgets/widgets-create-a-template.md",
       "redirect_url": "/windows/apps/develop/widgets/widgets-create-a-template",
@@ -11420,6 +11430,36 @@
       "redirect_url": "/windows/apps/dev-tools/visual-studio",
       "redirect_document_id": false
     },
+    {
+      "source_path": "hub/apps/whats-new/community.md",
+      "redirect_url": "/windows/apps/develop/support#stay-connected",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "hub/apps/get-started/ai-for-windows-developers.md",
+      "redirect_url": "/windows/apps/dev-tools/agentic-tools",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "hub/apps/how-tos/github-copilot-winui-vs.md",
+      "redirect_url": "/windows/apps/how-tos/ai-build",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "hub/apps/get-started/ai-build.md",
+      "redirect_url": "/windows/apps/how-tos/ai-build",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "hub/apps/get-started/ai-setup.md",
+      "redirect_url": "/windows/apps/how-tos/ai-setup",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "hub/apps/get-started/samples.md",
+      "redirect_url": "/windows/apps/dev-tools/samples",
+      "redirect_document_id": false
+    },
     {
       "source_path": "hub/apps/design/accessibility/accessibility.md",
       "redirect_url": "/windows/apps/design/accessibility/accessibility-overview",
@@ -11561,4 +11601,4 @@
       "redirect_document_id": false
     }
   ]
-}
+}

hub/apps/desktop/index.yml

@@ -8,114 +8,95 @@ metadata:
   description: This documentation provides the latest guidance about building desktop apps for Windows 11.
   ms.topic: landing-page
   ms.collection: collection
-  ms.date: 11/25/2025
+  ms.date: 03/27/2026
   keywords: windows win32, desktop development
 
 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new
 
 landingContent:
-  - title: Get ready for development
+  - title: Essentials
     linkLists:
       - linkListType: get-started
         links:
-          - text: What's new in Windows development
-            url: /windows/apps/whats-new/whats-new-for-developers
-          - text: Setup and tools
-            url: ../get-started/start-here.md
-          - text: An overview of UI frameworks
+          - text: Essentials
+            url: ../introduction.md
+          - text: Core concepts
             url: ../get-started/index.md
-          - text: Windows App SDK
-            url: ../windows-app-sdk/index.md
+          - text: Get started with WinUI
+            url: ../get-started/start-here.md
+          - text: Tools and samples
+            url: ../dev-tools/index.md
+          - text: Help and guidance
+            url: ../develop/support.md
+          - text: What's new
+            url: ../whats-new/whats-new-for-developers.md
 
-  - title: Design and UI
+  - title: Design
     linkLists:
       - linkListType: overview
         links:
-          - text: Design your app
+          - text: Design overview
             url: ../design/index.md
-          - text: Design resources and tools
+          - text: Design principles
+            url: ../design/design-principles.md
+          - text: Guidelines
+            url: ../design/guidelines-overview.md
+          - text: Tools and resources
             url: ../design/downloads/index.md
-          - text: Design for accessibility
-            url: ../design/accessibility/accessibility.md
-          - text: Design basics
-            url: ../design/basics/index.md
 
   - title: Develop
     linkLists:
       - linkListType: how-to-guide
         links:
-          - text: Develop apps
+          - text: Develop overview
             url: ../develop/index.md
-          - text: Best practices for Windows apps
-            url: ../get-started/best-practices.md
-          - text: Windows developer FAQ
-            url: ../get-started/windows-developer-faq.md
-          - text: Other development tools
-            url: /windows/dev-environment/
+          - text: Features
+            url: ../develop/features-overview.md
+          - text: Use features with other UI frameworks
+            url: ../desktop/modernize/index.md
+          - text: Platform
+            url: ../develop/platform/csharp-winrt/index.md
+          - text: API reference
+            url: ../api-reference/index.md
+          - text: Tools and samples
+            url: ../dev-tools/index.md
+          - text: Tutorials
+            url: ../winui/winui3/desktop-winui3-app-with-basic-interop.md
 
-  - title: Deploy
+  - title: Package and deploy
     linkLists:
-      - linkListType: overview
+      - linkListType: deploy
         links:
-          - text: Packaging and deployment overview
+          - text: Package and deploy overview
             url: ../package-and-deploy/index.md
-          - text: Learn about packaged and unpackaged apps
-            url: ../desktop/modernize/package-identity-overview.md
-          - text: Windows App SDK deployment guide
+          - text: Choose a packaging model
+            url: ../package-and-deploy/choose-packaging-model.md
+          - text: Packaging
+            url: ../package-and-deploy/packaging/index.md
+          - text: Windows App SDK deployment
             url: ../package-and-deploy/deploy-overview.md
-          - text: The MSIX app package format
-            url: /windows/msix
 
   - title: Distribute
     linkLists:
       - linkListType: overview
         links:
-          - text: Microsoft Store overview
+          - text: Choose a distribution path
+            url: ../package-and-deploy/choose-distribution-path.md
+          - text: Publish overview
             url: ../publish/index.md
+          - text: Get started with Microsoft Store
+            url: ../publish/get-started.md
           - text: Open a developer account
             url: ../publish/partner-center/open-a-developer-account.md
-          - text: Microsoft Store FAQ
-            url: ../publish/faq/get-started-with-the-microsoft-store.md    
-          - text: Microsoft Store Policies
-            url: ../publish/store-policies.md            
-
-  - title: Artificial intelligence and machine learning
-    linkLists:
-      - linkListType: concept
-        links:
-          - text: Windows AI
-            url: /windows/ai/
-          - text: GitHub Copilot extension for Visual Studio
-            url: /visualstudio/ide/visual-studio-github-copilot-extension
-          - text: App Actions on Windows
-            url: /windows/ai/app-actions/
-          - text: Windows ML
-            url: /windows/ai/new-windows-ml/overview
-
-  - title: API Reference
-    linkLists:
-      - linkListType: reference
-        links:
-          - text: WinRT API for the Windows SDK
-            url: /uwp/api/
-          - text: Win32 API for the Windows SDK
-            url: /windows/win32/api/
-          - text: WinRT API for the Windows App SDK
-            url: /windows/windows-app-sdk/api/winrt/
-          - text: Win32 API for the Windows App SDK
-            url: /windows/windows-app-sdk/api/win32/
-          - text: WinUI for UWP API reference
-            url: /windows/winui/api/
-  
-  - title: Community and support
-    linkLists:
-      - linkListType: overview
-        links:
-          - text: Microsoft Q&A Forum
-            url: /answers/questions/
-          - text: "@WindowsDocs"
-            url: https://twitter.com/WindowsDocs
-          - text: OneDevMinute on Microsoft Learn
-            url: /shows/One-Dev-Minute/?WT.mc_id=odm-c9-niner
-          - text: Windows developer support
-            url: https://developer.microsoft.com/windows/support
+          - text: Submit your app
+            url: ../publish/publish-your-app/msix/reserve-your-apps-name.md
+          - text: Get your app certified
+            url: ../publish/publish-your-app/msix/app-certification-process.md
+          - text: Monitor your app performance
+            url: ../publish/analyze-app-performance/msix.md
+          - text: Manage and update your app
+            url: ../publish/publish-your-app/msix/publish-update-to-your-app-on-store.md
+          - text: Manage your account
+            url: ../publish/partner-center/manage-account-users.md
+          - text: Microsoft Store policies and resources
+            url: ../publish/store-policies.md

hub/apps/desktop/modernize/grant-identity-to-nonpackaged-apps.md

@@ -3,14 +3,16 @@ title: Grant package identity by packaging with external location manually
 description: Learn how to grant package identity to an unpackaged Win32 app so that you can use modern Windows features in that app.
 ms.date: 04/08/2026
 ms.topic: how-to
-keywords: windows 10, desktop, sparse, package, identity, external, location, MSIX, Win32
+keywords: windows 10, desktop, sparse package, packaging with external location, package identity, external location, MSIX, Win32, unpackaged app
 ms.localizationpriority: medium
 ms.custom: RS5
 ---
 
 # Grant package identity by packaging with external location manually
 
-For the motivations behind adding package identity, as well as the differences between building
+> **Why do this?** Granting your app a package identity (also called a *sparse package* or *packaging with external location*) unlocks Windows platform features that are otherwise unavailable to unpackaged apps: toast and push notifications, background tasks, app extensions, share targets, file associations, startup tasks, privacy consent prompts, and Windows AI Foundry APIs — all without switching to full MSIX packaging or changing your existing installer.
+
+For more about the motivations behind adding package identity, as well as the differences between building
 identity packages in Visual Studio and building them manually, see
 [Overview](/windows/apps/desktop/modernize/grant-identity-to-nonpackaged-apps-overview).
 
@@ -264,7 +266,11 @@ var packageManager = new PackageManager();
 var options = new AddPackageOptions();
 options.ExternalLocationUri = externalUri;
 
-await packageManager.AddPackageByUriAsync(packageUri, options);
+var result = await packageManager.AddPackageByUriAsync(packageUri, options);
+if (result.ExtendedErrorCode != 0)
+{
+    throw new Exception($"Package registration failed: {result.ErrorText} (0x{result.ExtendedErrorCode:X8})");
+}
 
 ...
 
@@ -280,13 +286,14 @@ foreach (var package in packages)
 
 Note the below important details about this code:
 
-* Set `externalLocation` to the absolute path of your application's installation directory
-(without any executable names)
-* Set `packagePath` to the absolute path of the signed identity package produced in the previous step
+* Set `externalLocation` to the **absolute path** of your application's installation directory
+(without any executable names). `new Uri(somePath)` produces a `file:///` URI as required by the API.
+* Set `packagePath` to the **absolute path** of the signed identity package produced in the previous step
 (with the file name)
 * The `<IdentityPackageFamilyName>` can be found by running the `Get-AppxPackage <IdentityPackageName>`
 PowerShell command on a system where the identity package is registered. The `PackageFamilyName` property
 contains the value to use here.
+* Check `result.ExtendedErrorCode` after registration to surface actionable error details. See [Troubleshooting](#troubleshooting) for common error codes.
 
 #### Per-Machine (PackageManager)
 
@@ -336,6 +343,21 @@ Note the below important details about this code:
 PowerShell command on a system where the identity package is registered. The `PackageFamilyName`
 property contains the value to use here.
 
+## Troubleshooting
+
+The table below lists the most common errors when registering an identity package and how to fix them.
+
+| Error code | Symptom | Cause | Fix |
+|---|---|---|---|
+| `0x800B0109` / `CERT_E_UNTRUSTEDROOT` | `Add-AppxPackage` or `AddPackageByUriAsync` fails immediately | Self-signed certificate is not in the **Trusted People** store | Follow the [cert trust step](#build-and-sign-the-identity-package) above to import the public `.cer` into `Cert:\CurrentUser\TrustedPeople` |
+| `0x80073CF9` | Registration fails with "version already registered" | The exact same package version is already registered on this machine | Unregister the existing package first (`Remove-AppxPackage` or `RemovePackageAsync`), then re-register |
+| `0x80073D54` | Registration succeeds but identity is missing at runtime | `publisher`, `packageName`, or `applicationId` in the app's side-by-side manifest (`msix` element) don't match the identity package manifest | Ensure `Publisher`/`Name`/`Application Id` are identical in both manifests — see [Add identity metadata](#add-identity-metadata-to-your-desktop-application-manifests) |
+| Identity absent at runtime (no error) | `Package.Current` is null or `GetPackage()` returns nothing | The `ExternalLocation` path passed at registration doesn't match the directory where the app actually runs | Verify the absolute path passed as `ExternalLocation` is exactly the app's install directory |
+| `0x80073CF6` | Registration fails with "manifest invalid" | Manifest XML is malformed or a required attribute is missing | Validate the manifest with `MakeAppx.exe pack` — it reports schema errors. Ensure `uap10:AllowExternalContent` is `true` and `runFullTrust` capability is declared |
+
+> [!TIP]
+> For richer diagnostics, check the Windows **Event Viewer** under **Applications and Services Logs > Microsoft > Windows > AppxDeployment-Server**. It logs the full deployment error with context that isn't always surfaced in the API result or PowerShell output.
+
 ## Sample apps
 
 See the [PackageWithExternalLocation](https://aka.ms/sparsepkgsample) samples for fully functional

hub/apps/desktop/modernize/index.md

@@ -19,7 +19,7 @@ Use the table below to find the right starting point for your situation.
 | Add modern UI controls (Fluent, rounded corners, dark mode) to my WPF or Win32 app | [Host WinUI controls in a WPF app (XAML Islands)](xaml-islands/xaml-islands.md) |
 | Use Windows platform features (notifications, sharing, file pickers) in my WPF or WinForms app | [Call Windows Runtime APIs in desktop apps](desktop-to-uwp-enhance.md) |
 | Package my app for the Microsoft Store or enterprise deployment | [Package a desktop app with MSIX](/windows/msix/desktop/source-code-overview) |
-| Unlock features that require package identity (background tasks, app extensions) | [Grant identity to an unpackaged app](grant-identity-to-nonpackaged-apps-overview.md) |
+| Unlock features that require package identity (push notifications, background tasks, app extensions, Windows AI APIs, share targets, and more) | [Grant identity to an unpackaged app](grant-identity-to-nonpackaged-apps-overview.md) |
 | Integrate my app with Windows 11 shell features (snap layouts, context menus, taskbar) | [Integrate with Windows 11 features](desktop-to-uwp-extensions.md) |
 | Move to a fully modern app with WinUI 3 over time | [Migrate to WinUI 3](../../winui/winui3/create-your-first-winui3-app.md) |
 | Add on-device AI capabilities to my desktop app | [Windows AI Foundry](/windows/ai/overview) |
@@ -50,7 +50,7 @@ For more information, see [Building an MSIX package from your code](/windows/msi
 
 ## Features that require package identity
 
-Some Windows platform features — including certain background tasks, app extensions, and sharing targets — require your app to have a [package identity](/uwp/schemas/appxpackage/uapmanifestschema/element-identity) at runtime. You can grant identity to an unpackaged app without full MSIX packaging.
+Some Windows platform features — including push notifications, background tasks, app extensions, sharing targets, Windows AI Foundry APIs, file associations, and startup tasks — require your app to have a [package identity](/uwp/schemas/appxpackage/uapmanifestschema/element-identity) at runtime. You can grant identity to an unpackaged app without full MSIX packaging. This approach is sometimes called a *sparse package* or *packaging with external location*.
 
 For more information, see:
 - [Package identity overview](package-identity-overview.md)

hub/apps/dev-tools/agentic-tools.md

@@ -68,11 +68,9 @@ The WinUI 3 plugin addresses this directly: its custom instructions give Copilot
 
 ## Set up step-by-step
 
-For a complete walkthrough — including IDE setup, agent mode, MCP server configuration, and verification — see [Set up GitHub Copilot for Windows development](../get-started/ai-setup.md).
+For a complete walkthrough — including IDE setup, agent mode, MCP server configuration, and verification — see [Set up GitHub Copilot for Windows development](../how-tos/ai-setup.md).
 
 ## Related content
 
-- [Set up GitHub Copilot for Windows development](../get-started/ai-setup.md)
-- [AI-assisted Windows development](../get-started/ai-for-windows-developers.md)
-- [Build apps with AI built in](../get-started/ai-for-windows-developers.md#build-apps-with-ai-built-in) — Foundry Local, Phi Silica, and Windows AI APIs
-- [GitHub Copilot in Visual Studio](../how-tos/github-copilot-winui-vs.md)
+- [Set up GitHub Copilot for Windows development](../how-tos/ai-setup.md)
+- [Tutorial: Build a Windows app with GitHub Copilot](../how-tos/ai-build.md)

hub/apps/dev-tools/index.md

@@ -0,0 +1,17 @@
+---
+title: Tools and samples for Windows app development
+description: Explore tools, samples, and AI-powered resources for building Windows apps, including Visual Studio, agentic AI tools, code samples, and the winapp CLI.
+ms.topic: overview
+ms.date: 03/27/2026
+---
+
+# Tools and samples for Windows app development
+
+Build Windows apps more efficiently with the right tools, samples, and AI-powered resources. Whether you're setting up your development environment, looking for sample code to learn from, or enhancing your AI coding agent with Windows-specific context, this section brings together everything you need to be productive as a Windows app developer.
+
+| Resource | Description |
+|---|---|
+| [Agentic AI tools](agentic-tools.md) | Enhance your AI coding agent with Windows-specific context using the Microsoft Learn MCP Server and community plugins like the WinUI 3 Development plugin for GitHub Copilot. |
+| [Code samples](samples.md) | Browse sample apps that demonstrate Windows features, API usage patterns, and end-to-end scenarios — including the WinUI 3 Gallery and Windows App SDK samples. |
+| [Visual Studio](visual-studio.md) | The recommended IDE for building Windows apps with WinUI and the Windows App SDK, featuring XAML Hot Reload, Live Visual Tree, and rich debugging. |
+| [Windows App Development CLI (winapp CLI)](winapp-cli/index.md) | A command-line interface for managing Windows SDKs, packaging, app identity, manifests, certificates, and build tools across any app framework. |