From 3ece9892cbb27fdb1f33beb15e6ed68dd4ea4b98 Mon Sep 17 00:00:00 2001 From: Zachary Teutsch Date: Tue, 5 May 2026 17:13:18 -0400 Subject: [PATCH 01/19] add blog draft --- docs/blogs/dotnet-identity-and-packaging.md | 142 ++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/blogs/dotnet-identity-and-packaging.md diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md new file mode 100644 index 00000000..d4215b1e --- /dev/null +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -0,0 +1,142 @@ +# Packaging and Package Identity for .NET apps with Winapp CLI + +Package identity has often been a pain point for developers looking to build apps that integrate with Windows APIs. Many modern Windows features, like push notifications or the AI APIs, are gated behind package identity. For Windows apps that are unpackaged by default (like .NET console or WPF applications), this meant wrestling with package manifests, build configurations, and certs to bring your app up to speed. + +Now, with the [**winapp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. + +The winapp CLI enables a whole host of development related features, but we'll be highlighting two key capabilites to start: + +1. The winapp CLI integrates with existing dotnet tooling to enable you to test your application with package identity via `dotnet run` +2. The winapp CLI makes packaging applications as MSIX easy via `winapp pack` + + + + +If you want to follow along with the examples in this post, install the CLI with winget: + +``` +winget install Microsoft.winappcli --source winget +``` + +## `dotnet run` with Package Identity + +Once you have the winapp CLI installed, running your .NET app with identity is easy: + +### 1. Initialize your project with winapp. + +``` +winapp init --use-defaults +``` + +The init command takes care of all the prerequisites for enabling identity: +- Ensures the `TargetFramework` specified in your `.csproj` is supported +- Add `Microsoft.WindowsAppSDK`, `Microsoft.Windows.SDK.BuildTools`, and `Microsoft.Windows.SDK.BuildTools.WinApp` NuGet package references to your `.csproj` +- Generates both a `Package.appxmanifest` and required asset files, placed in an `Assets` directory + +If you want to more control over the init experience, run without the `--use-defaults` flag. + +### 2. Debug with `dotnet run` + +Once your project has been initialized with winapp, you can run your app as you would normally: + +``` +dotnet run +``` + +This will launch your app with package identity, allowing you to easily add and test Windows features within your app. + +For more details on how exactly the winapp CLI works with dotnet under the hood, checkout the [Dotnet run support docs.](https://github.com/microsoft/winappCli/blob/main/docs/dotnet-run-support.md) + +### 3. Adding an execution alias for console applications (optional) + +If you are building a console application, and want output to remain in the current terminal window, you will need to add an execution alias: + +1. Add the required alias to your `Package.appxmanifest` with winapp CLI: +``` +winapp manifest add-alias +``` +2. Tell your application to use the alias by opening your `.csproj` and adding this property to any ``: + +``` +true +``` + +### That's it. + +Those two steps (or three for console applications) are all that's required to run your application with identity locally. + +Now what about packaging? + +## Creating MSIX packages with `winapp pack` + +The winapp CLI provides `pack` and `cert generate` commands to streamline the MSIX creation process. Assuming you've initialized your project with `winapp init`, this is all it takes to create an installable MSIX: + +1. Build your application in `Release` configuration: +``` +dotnet build -c Release +``` +2. Generate a certificate with `winapp cert generate`, which will be named `devcert.pfx` by default: +``` +winapp cert generate +``` + +3. Package your application with the `pack` command, specifying your output directory and the cert you just generated: +``` +winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --cert .\devcert.pfx +``` + +The `pack` command will output a signed MSIX, ready to install. + +Before installing the MSIX, make sure to install the certificate: + +``` +winapp cert install .\devcert.pfx +``` + +And you're ready to test out your package! + + + +For a more in-depth breakdown for these scenarios with .NET, checkout the full [.NET guide.](https://github.com/microsoft/winappCli/blob/main/docs/guides/dotnet.md) + + +## What else can winapp do? + +Though package identity and packaging are the core of winapp CLI right now, it has other tools for Windows developers as well. Some highlights: + +* Run Windows build tools directly with the `tool` command +* Command line based inspection and interaction with UI elements with the `ui` command +* Access to the Microsoft Store CLI via the `store` command +* Support for other Windows-compatible frameworks for developers that work with a variety of stacks. + +Check out the [Usage documentaition](https://github.com/microsoft/winappCli/blob/main/docs/usage.md) for a full breakdown of available commands. + +## Don't like the terminal? Use the winapp VS Code extension instead. + +If you prefer to stay inside Visual Studio Code, and want an integrated debugging experience, we recently launched a [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinAppCLI.winapp) to expose winapp CLI functionality through VS Code commands. + +With some brief configuration, you can enable a "F5" debug experience, allowing you to launch and test your app from within VS Code with a button press. The extension also exposes commands for packaging and cert generation via the command palette. + +Once the extension is installed, hit `Ctrl+Shift+P` to open the command palette and type `winapp` to see available commands. + + + + For more info on the winapp extension, check out the [release blog post.](https://devblogs.microsoft.com/ifdef-windows/announcing-the-winapp-vs-code-extension-run-debug-and-package-windows-apps-in-vs-code/) + +## Get Started + +Install the CLI and try it on your next project: + +``` +winget install Microsoft.winappcli --source winget +``` + +Or if you prefer to try out the extension, visit the [Visual Studio Marketplace.](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinAppCLI.winapp) + +If you find any issues, have a feature request, or want to check out the source for winapp, head over to our [GitHub Repository.](https://github.com/microsoft/winappCli) + +For more getting started resources for .NET, check out the [.NET guide](https://github.com/microsoft/winappCli/blob/main/docs/guides/dotnet.md) or one of these samples: +- [.NET Console Application Sample](https://github.com/microsoft/winappCli/tree/main/samples/dotnet-app) +- [WPF Sample](https://github.com/microsoft/winappCli/tree/main/samples/wpf-app) + +Happy packaging! \ No newline at end of file From d08b2833a7f1d313c52611b9fe79c70fbbfaeadf Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 5 May 2026 17:25:03 -0400 Subject: [PATCH 02/19] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index d4215b1e..b881c522 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -1,4 +1,4 @@ -# Packaging and Package Identity for .NET apps with Winapp CLI +# Packaging and Package Identity for .NET apps with winapp CLI Package identity has often been a pain point for developers looking to build apps that integrate with Windows APIs. Many modern Windows features, like push notifications or the AI APIs, are gated behind package identity. For Windows apps that are unpackaged by default (like .NET console or WPF applications), this meant wrestling with package manifests, build configurations, and certs to bring your app up to speed. From 9b5054d4381726405b2632457cd5fb5728431c24 Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 5 May 2026 17:25:16 -0400 Subject: [PATCH 03/19] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index b881c522..0a9116a5 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -4,7 +4,7 @@ Package identity has often been a pain point for developers looking to build app Now, with the [**winapp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. -The winapp CLI enables a whole host of development related features, but we'll be highlighting two key capabilites to start: +The winapp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: 1. The winapp CLI integrates with existing dotnet tooling to enable you to test your application with package identity via `dotnet run` 2. The winapp CLI makes packaging applications as MSIX easy via `winapp pack` From 056078267ad7772f65f7e98aba2559d2148ff083 Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 5 May 2026 17:25:30 -0400 Subject: [PATCH 04/19] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 0a9116a5..f72ef161 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -30,10 +30,10 @@ winapp init --use-defaults The init command takes care of all the prerequisites for enabling identity: - Ensures the `TargetFramework` specified in your `.csproj` is supported -- Add `Microsoft.WindowsAppSDK`, `Microsoft.Windows.SDK.BuildTools`, and `Microsoft.Windows.SDK.BuildTools.WinApp` NuGet package references to your `.csproj` +- Adds `Microsoft.WindowsAppSDK`, `Microsoft.Windows.SDK.BuildTools`, and `Microsoft.Windows.SDK.BuildTools.WinApp` NuGet package references to your `.csproj` - Generates both a `Package.appxmanifest` and required asset files, placed in an `Assets` directory -If you want to more control over the init experience, run without the `--use-defaults` flag. +If you want more control over the init experience, run without the `--use-defaults` flag. ### 2. Debug with `dotnet run` From cc5e456c837798e59c78d38314f79b6b2ce40ebd Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 5 May 2026 17:25:45 -0400 Subject: [PATCH 05/19] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index f72ef161..5ca435f8 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -45,7 +45,7 @@ dotnet run This will launch your app with package identity, allowing you to easily add and test Windows features within your app. -For more details on how exactly the winapp CLI works with dotnet under the hood, checkout the [Dotnet run support docs.](https://github.com/microsoft/winappCli/blob/main/docs/dotnet-run-support.md) +For more details on how exactly the winapp CLI works with dotnet under the hood, check out the [`dotnet run` support docs](https://github.com/microsoft/winappCli/blob/main/docs/dotnet-run-support.md). ### 3. Adding an execution alias for console applications (optional) From 7e65679cf864debadc9f9f456c69795cab0d91f8 Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 5 May 2026 17:26:03 -0400 Subject: [PATCH 06/19] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 5ca435f8..988cd5d0 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -97,7 +97,7 @@ And you're ready to test out your package! -For a more in-depth breakdown for these scenarios with .NET, checkout the full [.NET guide.](https://github.com/microsoft/winappCli/blob/main/docs/guides/dotnet.md) +For a more in-depth breakdown for these scenarios with .NET, check out the full [.NET guide.](https://github.com/microsoft/winappCli/blob/main/docs/guides/dotnet.md) ## What else can winapp do? From 04f3abebffaecc5c7d855778334c19cd0db54895 Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 5 May 2026 17:26:30 -0400 Subject: [PATCH 07/19] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 988cd5d0..6d6a32dc 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -109,7 +109,7 @@ Though package identity and packaging are the core of winapp CLI right now, it h * Access to the Microsoft Store CLI via the `store` command * Support for other Windows-compatible frameworks for developers that work with a variety of stacks. -Check out the [Usage documentaition](https://github.com/microsoft/winappCli/blob/main/docs/usage.md) for a full breakdown of available commands. +Check out the [Usage documentation](https://github.com/microsoft/winappCli/blob/main/docs/usage.md) for a full breakdown of available commands. ## Don't like the terminal? Use the winapp VS Code extension instead. From 7a2a29d063aecd5c4b59784e9598fea95645778a Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 12 May 2026 15:21:50 -0400 Subject: [PATCH 08/19] Update docs/blogs/dotnet-identity-and-packaging.md --- docs/blogs/dotnet-identity-and-packaging.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 6d6a32dc..8638b7a5 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -80,10 +80,7 @@ dotnet build -c Release winapp cert generate ``` -3. Package your application with the `pack` command, specifying your output directory and the cert you just generated: -``` -winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --cert .\devcert.pfx -``` +3. Package your application with the `pack` command, specifying your output directory and the cert you just generated. Run this command from your project root: The `pack` command will output a signed MSIX, ready to install. From 773ec00b58a1fea197c9a0aa55944e3c30f5224b Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 12 May 2026 15:23:07 -0400 Subject: [PATCH 09/19] Update docs/blogs/dotnet-identity-and-packaging.md Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 8638b7a5..c5647637 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -2,7 +2,7 @@ Package identity has often been a pain point for developers looking to build apps that integrate with Windows APIs. Many modern Windows features, like push notifications or the AI APIs, are gated behind package identity. For Windows apps that are unpackaged by default (like .NET console or WPF applications), this meant wrestling with package manifests, build configurations, and certs to bring your app up to speed. -Now, with the [**winapp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. +Now, with the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. The winapp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: From 91b5cc5fe2fd5bd43b99567ff43111c77448364b Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 12 May 2026 15:23:20 -0400 Subject: [PATCH 10/19] Update docs/blogs/dotnet-identity-and-packaging.md Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index c5647637..7a84b835 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -7,7 +7,7 @@ Now, with the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can The winapp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: 1. The winapp CLI integrates with existing dotnet tooling to enable you to test your application with package identity via `dotnet run` -2. The winapp CLI makes packaging applications as MSIX easy via `winapp pack` +2. The WinApp CLI makes packaging applications as MSIX easy via `winapp pack` From ff63e04677f6d05aff41785f4c42ff5c78a56808 Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 12 May 2026 15:23:32 -0400 Subject: [PATCH 11/19] Update docs/blogs/dotnet-identity-and-packaging.md Co-authored-by: Nikola Metulev --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 7a84b835..67d6cbe8 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -1,4 +1,4 @@ -# Packaging and Package Identity for .NET apps with winapp CLI +# Packaging and Package Identity for .NET apps with winapp CLI on Windows Package identity has often been a pain point for developers looking to build apps that integrate with Windows APIs. Many modern Windows features, like push notifications or the AI APIs, are gated behind package identity. For Windows apps that are unpackaged by default (like .NET console or WPF applications), this meant wrestling with package manifests, build configurations, and certs to bring your app up to speed. From 9b69fe31c5702beb3768788b7bd255f2e539ba0c Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 12 May 2026 15:23:56 -0400 Subject: [PATCH 12/19] Update docs/blogs/dotnet-identity-and-packaging.md Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 67d6cbe8..9c3d2a88 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -4,7 +4,7 @@ Package identity has often been a pain point for developers looking to build app Now, with the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. -The winapp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: +The WinApp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: 1. The winapp CLI integrates with existing dotnet tooling to enable you to test your application with package identity via `dotnet run` 2. The WinApp CLI makes packaging applications as MSIX easy via `winapp pack` From 6b25198c569fb3b6b43f739a2b1769f09e5a65b6 Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 12 May 2026 15:24:08 -0400 Subject: [PATCH 13/19] Update docs/blogs/dotnet-identity-and-packaging.md Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 9c3d2a88..5b252e55 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -6,7 +6,7 @@ Now, with the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can The WinApp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: -1. The winapp CLI integrates with existing dotnet tooling to enable you to test your application with package identity via `dotnet run` +1. The WinApp CLI integrates with existing dotnet tooling to enable you to test your application with package identity via `dotnet run` 2. The WinApp CLI makes packaging applications as MSIX easy via `winapp pack` From 1f0919842c0e6a6c0f0fa9a56094a3d5f26b3a8f Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 12 May 2026 15:24:20 -0400 Subject: [PATCH 14/19] Update docs/blogs/dotnet-identity-and-packaging.md Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 5b252e55..ef636ca9 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -51,7 +51,7 @@ For more details on how exactly the winapp CLI works with dotnet under the hood, If you are building a console application, and want output to remain in the current terminal window, you will need to add an execution alias: -1. Add the required alias to your `Package.appxmanifest` with winapp CLI: +1. Add the required alias to your `Package.appxmanifest` with WinApp CLI: ``` winapp manifest add-alias ``` From ce75ed57e48c483c288f397fb5a4555731e813d8 Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Tue, 12 May 2026 15:24:37 -0400 Subject: [PATCH 15/19] Update docs/blogs/dotnet-identity-and-packaging.md Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com> --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index ef636ca9..1a5fdf8b 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -69,7 +69,7 @@ Now what about packaging? ## Creating MSIX packages with `winapp pack` -The winapp CLI provides `pack` and `cert generate` commands to streamline the MSIX creation process. Assuming you've initialized your project with `winapp init`, this is all it takes to create an installable MSIX: +The WinApp CLI provides `pack` and `cert generate` commands to streamline the MSIX creation process. Assuming you've initialized your project with `winapp init`, this is all it takes to create an installable MSIX: 1. Build your application in `Release` configuration: ``` From 92d3207b97d493330f2302ccbca5e2c8e654054c Mon Sep 17 00:00:00 2001 From: Zachary Teutsch Date: Tue, 12 May 2026 16:31:42 -0400 Subject: [PATCH 16/19] address team feedback --- docs/blogs/dotnet-identity-and-packaging.md | 99 ++++++++++++++++----- 1 file changed, 75 insertions(+), 24 deletions(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 1a5fdf8b..ef8cdff1 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -1,14 +1,16 @@ -# Packaging and Package Identity for .NET apps with winapp CLI on Windows +# Packaging and Package Identity for .NET apps with WinApp CLI on Windows -Package identity has often been a pain point for developers looking to build apps that integrate with Windows APIs. Many modern Windows features, like push notifications or the AI APIs, are gated behind package identity. For Windows apps that are unpackaged by default (like .NET console or WPF applications), this meant wrestling with package manifests, build configurations, and certs to bring your app up to speed. +Package identity has often been a pain point for developers looking to build apps that integrate with Windows APIs. Many modern Windows features, like push notifications or the AI APIs, are gated behind package identity. For Windows apps that are unpackaged by default (like .NET console or WPF applications), this meant wrestling with package manifests, build configurations, and certs to bring your app up to speed. -Now, with the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. +With the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. The WinApp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: 1. The WinApp CLI integrates with existing dotnet tooling to enable you to test your application with package identity via `dotnet run` 2. The WinApp CLI makes packaging applications as MSIX easy via `winapp pack` +The WinApp CLI works for .NET console, WPF, WinForms, and WinUI3 applications. + @@ -22,18 +24,21 @@ winget install Microsoft.winappcli --source winget Once you have the winapp CLI installed, running your .NET app with identity is easy: -### 1. Initialize your project with winapp. +### 1. Initialize your project with winapp ``` winapp init --use-defaults ``` The init command takes care of all the prerequisites for enabling identity: -- Ensures the `TargetFramework` specified in your `.csproj` is supported -- Adds `Microsoft.WindowsAppSDK`, `Microsoft.Windows.SDK.BuildTools`, and `Microsoft.Windows.SDK.BuildTools.WinApp` NuGet package references to your `.csproj` -- Generates both a `Package.appxmanifest` and required asset files, placed in an `Assets` directory +- Ensures the `TargetFramework` specified in your `.csproj` is targeting a compatible version of the Windows platform. This is required to properly enable access to Windows APIs. +- Adds three package references to your `.csproj`: + - `Microsoft.WindowsAppSDK` This dependency is the Windows SDK itself, and grants access to Windows APIs. + - `Microsoft.Windows.SDK.BuildTools` Windows Build Tools are required for packaging and signing your application. + - `Microsoft.Windows.SDK.BuildTools.WinApp` This is the NuGet package for WinApp itself. This dependency enables seamless `dotnet run` usage via WinApp. +- Generates both a `Package.appxmanifest` and required asset files, placed in an `Assets` directory. These files are required to grant package identity. -If you want more control over the init experience, run without the `--use-defaults` flag. +If you want more control over the init experience, run without the `--use-defaults` flag. This will give you control over versioning, package and publisher name, and allow you to manage which dependencies are added to your project. ### 2. Debug with `dotnet run` @@ -45,6 +50,12 @@ dotnet run This will launch your app with package identity, allowing you to easily add and test Windows features within your app. +If you want to unregister your application and clean up any app data after launching with identity, run this command from the project root: + +``` +winapp unregister +``` + For more details on how exactly the winapp CLI works with dotnet under the hood, check out the [`dotnet run` support docs](https://github.com/microsoft/winappCli/blob/main/docs/dotnet-run-support.md). ### 3. Adding an execution alias for console applications (optional) @@ -63,7 +74,7 @@ winapp manifest add-alias ### That's it. -Those two steps (or three for console applications) are all that's required to run your application with identity locally. +Those two steps (or three for console applications) are all that's required to run your application with identity locally. Your app will now be able to access Windows features and APIs (like notifications, file handlers, and background tasks) that were gated behind identity. Now what about packaging? @@ -75,24 +86,18 @@ The WinApp CLI provides `pack` and `cert generate` commands to streamline the MS ``` dotnet build -c Release ``` -2. Generate a certificate with `winapp cert generate`, which will be named `devcert.pfx` by default: -``` -winapp cert generate -``` -3. Package your application with the `pack` command, specifying your output directory and the cert you just generated. Run this command from your project root: +2. Package your application with the `pack` command, specifying your output directory. Run this command from your project root: -The `pack` command will output a signed MSIX, ready to install. +The `pack` command will output a signed MSIX. -Before installing the MSIX, make sure to install the certificate: + -``` -winapp cert install .\devcert.pfx -``` +### Testing locally +If you need to test locally, you will need to sign your package with a self-signed certificate. -And you're ready to test out your package! +WinApp can generate certificates via the `winapp cert generate` command and install them via `winapp cert install`. - For a more in-depth breakdown for these scenarios with .NET, check out the full [.NET guide.](https://github.com/microsoft/winappCli/blob/main/docs/guides/dotnet.md) @@ -112,13 +117,59 @@ Check out the [Usage documentation](https://github.com/microsoft/winappCli/blob/ If you prefer to stay inside Visual Studio Code, and want an integrated debugging experience, we recently launched a [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinAppCLI.winapp) to expose winapp CLI functionality through VS Code commands. -With some brief configuration, you can enable a "F5" debug experience, allowing you to launch and test your app from within VS Code with a button press. The extension also exposes commands for packaging and cert generation via the command palette. +With some brief configuration, you can enable a "F5" debug experience, allowing you to launch and test your app from within VS Code with a button press. To enable F5 debugging via the WinApp extension: + +1. Update your `launch.json` to include a `winapp` configuration: + +```json +{ + "version": "0.3.0", + "configurations": [ + { + "type": "winapp", + "request": "launch", + "name": "WinApp: Launch and Attach" + } + ] +} +``` + +2. Automate the build process by defining a build task in `.vscode/tasks.json`: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "command": "dotnet", + "type": "process", + "args": ["build", "${workspaceFolder}"], + "problemMatcher": "$msCompile" + } + ] +} +``` + +3. Update the `winapp` configuration in your `launch.json` to reference your build task: + +```json +{ + "type": "winapp", + "request": "launch", + "name": "WinApp: Launch and Attach", + "preLaunchTask": "build" +} +``` + +Now, hitting F5 will automatically build and launch your application. -Once the extension is installed, hit `Ctrl+Shift+P` to open the command palette and type `winapp` to see available commands. +### Access WinApp commands via the command palette +In addition to integrated launching, the extension also exposes much of the CLI's functionality via the VS Code command palette. Hit `Ctrl+Shift+P` to open the command palette and type `winapp` to see available commands, including packaging and signing commands. - For more info on the winapp extension, check out the [release blog post.](https://devblogs.microsoft.com/ifdef-windows/announcing-the-winapp-vs-code-extension-run-debug-and-package-windows-apps-in-vs-code/) +For more info on the winapp extension, check out the [release blog post.](https://devblogs.microsoft.com/ifdef-windows/announcing-the-winapp-vs-code-extension-run-debug-and-package-windows-apps-in-vs-code/) ## Get Started From bf2fca279d64433b8ed001b703bfc58bc64828d9 Mon Sep 17 00:00:00 2001 From: Zachary Teutsch Date: Wed, 13 May 2026 15:24:27 -0400 Subject: [PATCH 17/19] add section to show value of package identity --- docs/blogs/dotnet-identity-and-packaging.md | 23 +++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index ef8cdff1..0dcc5053 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -2,24 +2,35 @@ Package identity has often been a pain point for developers looking to build apps that integrate with Windows APIs. Many modern Windows features, like push notifications or the AI APIs, are gated behind package identity. For Windows apps that are unpackaged by default (like .NET console or WPF applications), this meant wrestling with package manifests, build configurations, and certs to bring your app up to speed. -With the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. +With the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. Inside the .NET ecosystem, WinApp supports .NET console, WPF, WinForms, and WinUI3 applications. The WinApp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: 1. The WinApp CLI integrates with existing dotnet tooling to enable you to test your application with package identity via `dotnet run` 2. The WinApp CLI makes packaging applications as MSIX easy via `winapp pack` -The WinApp CLI works for .NET console, WPF, WinForms, and WinUI3 applications. - - - - If you want to follow along with the examples in this post, install the CLI with winget: + ``` winget install Microsoft.winappcli --source winget ``` +### What is package identity and why would I want it? +Package identity is a unique identifier for your application within Windows. You can think of granting package identity as "registering" your application within the operating system. + +An app that has been granted identity can more effectively integrate with the Windows platform, enabling access to Windows APIs and features that would otherwise be blocked without it. Some of the capabilities that become available with package identity include: +* Background tasks +* Push and toast notifications +* Share target +* File handlers +* Windows AI APIs +* and many others! + +Long story short, package identity enables a richer experience for your application on Windows. + +Let's take a look at how WinApp can make the process of granting package identity straightforward. + ## `dotnet run` with Package Identity Once you have the winapp CLI installed, running your .NET app with identity is easy: From 70c9ed9b08817aa8417b937ae9ad9f8f81a9bd57 Mon Sep 17 00:00:00 2001 From: Zach Teutsch <88554871+zateutsch@users.noreply.github.com> Date: Thu, 21 May 2026 11:18:07 -0400 Subject: [PATCH 18/19] Update docs/blogs/dotnet-identity-and-packaging.md --- docs/blogs/dotnet-identity-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 0dcc5053..03ec5c83 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -67,7 +67,7 @@ If you want to unregister your application and clean up any app data after launc winapp unregister ``` -For more details on how exactly the winapp CLI works with dotnet under the hood, check out the [`dotnet run` support docs](https://github.com/microsoft/winappCli/blob/main/docs/dotnet-run-support.md). +For more details on how exactly the WinApp CLI works with dotnet under the hood, check out the [`dotnet run` support docs](https://github.com/microsoft/winappCli/blob/main/docs/dotnet-run-support.md). ### 3. Adding an execution alias for console applications (optional) From 83cd9c142bbc9a9f62f56fa3be42eed81907599d Mon Sep 17 00:00:00 2001 From: Zachary Teutsch Date: Thu, 21 May 2026 11:56:22 -0400 Subject: [PATCH 19/19] address nikola feedback --- docs/blogs/dotnet-identity-and-packaging.md | 55 +++++++++++++++++---- 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/docs/blogs/dotnet-identity-and-packaging.md b/docs/blogs/dotnet-identity-and-packaging.md index 03ec5c83..93ba9e39 100644 --- a/docs/blogs/dotnet-identity-and-packaging.md +++ b/docs/blogs/dotnet-identity-and-packaging.md @@ -2,7 +2,7 @@ Package identity has often been a pain point for developers looking to build apps that integrate with Windows APIs. Many modern Windows features, like push notifications or the AI APIs, are gated behind package identity. For Windows apps that are unpackaged by default (like .NET console or WPF applications), this meant wrestling with package manifests, build configurations, and certs to bring your app up to speed. -With the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. Inside the .NET ecosystem, WinApp supports .NET console, WPF, WinForms, and WinUI3 applications. +With the [**WinApp CLI**](https://github.com/microsoft/winappCli), you can quickly tackle the problem of package identity, both in the context of local running and debugging, and for packaging applications as MSIX for distribution. WinApp is compatible with any .NET desktop framework. The WinApp CLI enables a whole host of development related features, but we'll be highlighting two key capabilities to start: @@ -38,28 +38,27 @@ Once you have the winapp CLI installed, running your .NET app with identity is e ### 1. Initialize your project with winapp ``` -winapp init --use-defaults +winapp init . --use-defaults ``` The init command takes care of all the prerequisites for enabling identity: - Ensures the `TargetFramework` specified in your `.csproj` is targeting a compatible version of the Windows platform. This is required to properly enable access to Windows APIs. -- Adds three package references to your `.csproj`: - - `Microsoft.WindowsAppSDK` This dependency is the Windows SDK itself, and grants access to Windows APIs. - - `Microsoft.Windows.SDK.BuildTools` Windows Build Tools are required for packaging and signing your application. - - `Microsoft.Windows.SDK.BuildTools.WinApp` This is the NuGet package for WinApp itself. This dependency enables seamless `dotnet run` usage via WinApp. +- Adds two package references to your `.csproj`: + - `Microsoft.WindowsAppSDK` — This dependency is the Windows SDK itself, and grants access to Windows APIs. + - `Microsoft.Windows.SDK.BuildTools.WinApp` — This is the NuGet package for WinApp itself. This dependency enables seamless `dotnet run` usage via WinApp. - Generates both a `Package.appxmanifest` and required asset files, placed in an `Assets` directory. These files are required to grant package identity. -If you want more control over the init experience, run without the `--use-defaults` flag. This will give you control over versioning, package and publisher name, and allow you to manage which dependencies are added to your project. +If you want more control over the init experience, run without the `--use-defaults` flag. This will give you control over versioning, package and publisher name, and allow you to manage which dependencies are added to your project. Additionally, if you already have any of the prerequisites handled by the init command, WinApp will not overwrite them. ### 2. Debug with `dotnet run` -Once your project has been initialized with winapp, you can run your app as you would normally: +Once your project has been initialized with WinApp, you can run your app as you would normally: ``` dotnet run ``` -This will launch your app with package identity, allowing you to easily add and test Windows features within your app. +Because the WinApp NuGet package is referenced by your project, `dotnet run` will call on WinApp to run your application. This will launch your app with package identity, allowing you to easily add and test Windows features within your app. If you want to unregister your application and clean up any app data after launching with identity, run this command from the project root: @@ -67,7 +66,39 @@ If you want to unregister your application and clean up any app data after launc winapp unregister ``` -For more details on how exactly the WinApp CLI works with dotnet under the hood, check out the [`dotnet run` support docs](https://github.com/microsoft/winappCli/blob/main/docs/dotnet-run-support.md). +Additionally, if you want to disable running as a packaged application, you can add this property to your `.csproj`: + +```xml + + None + +``` + +#### Passing arguments to WinApp + +To customize `run` behavior, you can pass arguments to WinApp by setting properties in your `.csproj`: + +```xml + + + $(MSBuildProjectDirectory)\custom\Package.appxmanifest + + + --debug --verbose + + + true + + + true + + + true + +``` + +For more details on how exactly the WinApp CLI works with dotnet under the hood and for further guidance on customizing the run experience, check out the [`dotnet run` support docs](https://github.com/microsoft/winappCli/blob/main/docs/dotnet-run-support.md). + ### 3. Adding an execution alias for console applications (optional) @@ -100,6 +131,10 @@ dotnet build -c Release 2. Package your application with the `pack` command, specifying your output directory. Run this command from your project root: +``` +winapp pack .\bin\Release\net10.0-windows10.0.26100.0 +``` + The `pack` command will output a signed MSIX.