Skip to content

complete nuspec #6267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MuyuanMS merged 5 commits into from
Mar 9, 2026
+104 −67
Merged

complete nuspec #6267

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c090622
complete nuspec
MuyuanMS Mar 3, 2026
d6defbd
Update dev/VSIX/DotnetNewTemplates/WinAppSdk.CSharp.DotnetNewTemplate…
MuyuanMS Mar 4, 2026
1abe6ba
Update dev/VSIX/DotnetNewTemplates/WinAppSdk.CSharp.DotnetNewTemplate…
MuyuanMS Mar 4, 2026
927214b
Update dev/VSIX/DotnetNewTemplates/README.md
MuyuanMS Mar 4, 2026
c40b6dc
Resolve comments
MuyuanMS Mar 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 101 additions & 65 deletions dev/VSIX/DotnetNewTemplates/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,81 +1,117 @@
# Windows App SDK .NET CLI Templates

This directory contains the assets that produce the `dotnet new` template pack for the
Windows App SDK C# Desktop templates. The templates are built directly from the
existing Visual Studio template sources under `dev/VSIX/ProjectTemplates/Desktop/CSharp`
and `dev/VSIX/ItemTemplates/Desktop/CSharp`, so we only maintain one copy of the XAML,
code-behind, and project files.

## Templates

| Short name | Identity | Type | Description |
|-----------------------|-----------------------------------------------|----------|-----------------------------------------------------------|
| `winui` | `Microsoft.WindowsAppSDK.WinUI.CSharp.BlankApp` | Project | WinUI 3 blank app that uses single-project MSIX tooling |
| `winui-navview` | `Microsoft.WindowsAppSDK.WinUI.CSharp.NavigationApp` | Project | WinUI 3 NavigationView starter app |
| `winui-lib` | `Microsoft.WindowsAppSDK.WinUI.CSharp.ClassLibrary` | Project | WinUI 3 class library for sharing UI components |
| `winui-unittest` | `Microsoft.WindowsAppSDK.WinUI.CSharp.UnitTest` | Project | WinUI 3 packaged test app configured for MSTest |
| `winui-page` | `Microsoft.WindowsAppSDK.WinUI.CSharp.Item.Page` | Item | Adds a blank WinUI 3 Page |
| `winui-window` | `Microsoft.WindowsAppSDK.WinUI.CSharp.Item.Window` | Item | Adds a blank WinUI 3 Window |
| `winui-usercontrol` | `Microsoft.WindowsAppSDK.WinUI.CSharp.Item.UserControl.Legacy` | Item | Adds a WinUI 3 UserControl |
| `winui-templatedcontrol` | `Microsoft.WindowsAppSDK.WinUI.CSharp.Item.TemplatedControl` | Item | Adds a templated WinUI 3 control skeleton |
| `winui-resourcedictionary` | `Microsoft.WindowsAppSDK.WinUI.CSharp.Item.ResourceDictionary`| Item | Adds a WinUI 3 ResourceDictionary |
| `winui-resw` | `Microsoft.WindowsAppSDK.WinUI.CSharp.Item.Resw` | Item | Adds a RESW resource file |
| `winui-dialog` | `Microsoft.WindowsAppSDK.WinUI.CSharp.Item.ContentDialog` | Item | Adds a WinUI 3 ContentDialog |

Run `dotnet new <short name> -n MyProject` to create a project from the pack once it
is installed. Item templates only surface when `dotnet new` is executed inside a
WinUI project folder (or when `--project` points to one) so that commands stay
context-aware.
# Windows App SDK WinUI 3 C# Templates

### Choosing a Target Framework
Official WinUI 3 project and item templates for the
[Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/),
designed for use with the .NET CLI (`dotnet new`). This template pack provides
the same starting points available in Visual Studio — blank apps, navigation
views, class libraries, unit test projects, and common WinUI UI items — right
from the command line.

## Installation

```shell
dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates
```

All templates currently default to `net8.0` for compatibility with the widest
set of Windows App SDK tooling. To target a newer .NET version you can either:
## Available Templates

1. Pass `--dotnet-version <tfm>` (for example `--dotnet-version net10.0`) when
running `dotnet new ...`.
2. Edit the generated `.csproj` afterward and change `<TargetFramework>` (and
any related `<RuntimeIdentifiers>` entries) to your preferred TFM.
### Project Templates

`dotnet new winui --dotnet-version net10.0 -n MyApp` is the quickest way to spin
up a project that targets .NET 10 while still using the same template payload.
| Short Name | Description |
|------------------|----------------------------------------------------------|
| `winui` | WinUI 3 blank app with single-project MSIX packaging |
| `winui-navview` | WinUI 3 NavigationView starter app |
| `winui-lib` | WinUI 3 class library for sharing UI components |
| `winui-unittest` | WinUI 3 packaged test app configured for MSTest |

### CLI Quick Reference
### Item Templates

- Create a blank WinUI app: `dotnet new winui -n MyApp`
- Add a page to an existing project: `dotnet new winui-page -n SettingsPage --project .\MyApp.csproj`
- Add a user control: `dotnet new winui-usercontrol -n ProfileCard --project .\MyApp.csproj`
- Launch the packaged app directly: `dotnet run -c Debug -p:Platform=$env:PROCESSOR_ARCHITECTURE`
- Launch with WinApp Runtime tooling (after building/registering): `winapp run .\MyApp\bin\x64\Debug\<TargetFramework>\MyApp.exe`
| Short Name | Description |
|----------------------------|------------------------------------|
| `winui-page` | Blank WinUI 3 Page |
| `winui-window` | Blank WinUI 3 Window |
| `winui-usercontrol` | WinUI 3 UserControl |
| `winui-templatedcontrol` | WinUI 3 templated control |
| `winui-resourcedictionary` | WinUI 3 ResourceDictionary |
| `winui-resw` | RESW resource file |
| `winui-dialog` | WinUI 3 ContentDialog |

Whenever possible prefer the CLI scaffolding over hand authoring new files so
token replacements, namespaces, and resource wiring stay consistent.
Replace `<TargetFramework>` with the exact folder emitted by your build (for
example `net8.0-windows10.0.19041.0`).
Item templates are context-aware and only surface when `dotnet new` is executed
inside a WinUI project folder or when `--project` points to one.

## Local testing workflow
## Quick Start

1. Pack the templates: `dotnet pack dev/VSIX/DotnetNewTemplates/WinAppSdk.CSharp.DotnetNewTemplates.csproj -c Release -o localpackages`.
2. If you already have an older version installed, remove it with `dotnet new uninstall Microsoft.WindowsAppSDK.WinUI.CSharp.Templates`.
3. Install the freshly packed nupkg: `dotnet new install .\localpackages\Microsoft.WindowsAppSDK.WinUI.CSharp.Templates.<version>.nupkg`. The `<version>` suffix (for example `0.0.1-experimental`) is controlled by the `<Version>` value in [WinAppSdk.CSharp.DotnetNewTemplates.csproj](WinAppSdk.CSharp.DotnetNewTemplates.csproj#L3-L38), so bump it there when needed.
### Create a new WinUI 3 app

## Building the NuGet package
```shell
dotnet new winui -n MyApp
cd MyApp
dotnet build -p:Platform=x64
dotnet run -c Debug -p:Platform=x64
```

The pack project lives at `dev/VSIX/DotnetNewTemplates/WinAppSdk.CSharp.DotnetNewTemplates.csproj`.
It links the Visual Studio template files into the template pack so there is a single
source of truth. The build produces a template NuGet package in `localpackages/`:
### Add items to an existing project

```powershell
cd <repo-root>
dotnet pack dev/VSIX/DotnetNewTemplates/WinAppSdk.CSharp.DotnetNewTemplates.csproj -c Release -o localpackages
```shell
dotnet new winui-page -n SettingsPage --project .\MyApp.csproj
dotnet new winui-usercontrol -n ProfileCard --project .\MyApp.csproj
dotnet new winui-window -n SecondaryWindow --project .\MyApp.csproj
```

`BuildAll.ps1` also runs the same packing step so official builds automatically emit
the template pack alongside the other Windows App SDK artifacts.
### Choosing a Target Framework

All templates default to `net8.0-windows10.0.19041.0`. To target a different
.NET version, pass `--dotnet-version` when creating the project:

## Validation checklist
```shell
dotnet new winui --dotnet-version net10.0 -n MyApp
```

- Run `dotnet pack` locally (as shown above) and use `dotnet new install` to verify each template still scaffolds and runs.
- Execute `dotnet new --list | findstr winui` (PowerShell: `dotnet new --list | Select-String winui`) to confirm the pack metadata surfaces correctly.
- Open the generated projects in Visual Studio or VS Code, build them for x86/x64/ARM64, and ensure packaged deployments succeed on Windows 10 version 1809 or later.
- When contributing changes, note the updated template version in your PR description so downstream publishing systems pick up the new package.
You can also edit the generated `.csproj` afterward and change
`<TargetFramework>` (and any related `<RuntimeIdentifiers>` entries) to your
preferred TFM.

## Prerequisites

- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later
- Windows 10 version 1809 (build 17763) or later
- [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/)
workload

## Resources

- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/)
- [WinUI 3 documentation](https://learn.microsoft.com/windows/apps/winui/winui3/)
- [Release notes](https://github.com/microsoft/WindowsAppSDK/releases)
- [File an issue](https://github.com/microsoft/WindowsAppSDK/issues)

## Contributing

This template pack is built from the
[WindowsAppSDK](https://github.com/microsoft/WindowsAppSDK) repository under
`dev/VSIX/DotnetNewTemplates/`. The templates share the same XAML, code-behind,
and project files as the Visual Studio templates under
`dev/VSIX/ProjectTemplates/` and `dev/VSIX/ItemTemplates/`, so there is only one
copy to maintain.

### Local Testing

1. Pack the templates:
```shell
dotnet pack dev/VSIX/DotnetNewTemplates/WinAppSdk.CSharp.DotnetNewTemplates.csproj -c Release -o localpackages
```
2. Uninstall any previous version:
```shell
dotnet new uninstall Microsoft.WindowsAppSDK.WinUI.CSharp.Templates
```
3. Install the local package:
```shell
dotnet new install ./localpackages/Microsoft.WindowsAppSDK.WinUI.CSharp.Templates.<version>.nupkg
```

### Validation Checklist

- Run `dotnet pack` locally and `dotnet new install` to verify each template scaffolds and builds.
- Run `dotnet new list | findstr winui` to confirm all templates are registered.
- Build generated projects for x64, x86, and ARM64 in Visual Studio or VS Code.
- Test packaged deployments on Windows 10 version 1809 or later.
5 changes: 3 additions & 2 deletions dev/VSIX/DotnetNewTemplates/WinAppSdk.CSharp.DotnetNewTemplates.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,17 @@
<PackageType>Template</PackageType>
<PackageId>Microsoft.WindowsAppSDK.WinUI.CSharp.Templates</PackageId>
<Version>0.0.1-experimental</Version>
<Title>WinUI 3 C# Templates</Title>
<Authors>Microsoft</Authors>
<Company>Microsoft</Company>
<Description>Official WinUI 3 project and item templates for the Windows App SDK. Install this pack to use dotnet new for blank apps, navigation views, libraries, unit tests, and common WinUI UI items that match the Visual Studio experience.</Description>
<Description>Official WinUI 3 project and item templates. Install this pack to use dotnet new for different types of apps, class libraries, unit tests and common WinUI controls.</Description>
<PackageTags>windows;winappsdk;winui;winui3;desktop;dotnet-new;templates;csharp</PackageTags>
<PackageProjectUrl>https://learn.microsoft.com/windows/apps/windows-app-sdk/</PackageProjectUrl>
<RepositoryUrl>https://github.com/microsoft/WindowsAppSDK</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageReadmeFile>README.md</PackageReadmeFile>
<Copyright>(c) Microsoft Corporation. All rights reserved.</Copyright>
<Copyright>© Microsoft Corporation. All rights reserved.</Copyright>
<PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
<PackageReleaseNotes>See https://github.com/microsoft/WindowsAppSDK/releases for release notes.</PackageReleaseNotes>
<SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>
Expand Down