Dotnet Templates: use winappCli 3.0.1 (Microsoft.Windows.SDK.BuildTools.WinApp)

[DinahK-2SO]

Summary

1. Make dotnet run works out of box on the WinUI templates — wire the new
   Microsoft.Windows.SDK.BuildTools.WinApp 0.3.1
   NuGet package into the four packaged WinUI C# templates so users get
   loose-layout package identity + AUMID launch out of the box.
2. Modernize the agent instructions — Agents.md and the
   instructions/*.instructions.md files now teach AI agents to use the
   public winapp CLI (winappCli 0.3) instead of hand-rolled
   Add-AppxPackage -Register / MakeAppx / SignTool invocations.
3. Update README
4. Extra fixes of errors in existing templates.

Quick start

dotnet new winui -n MyApp
cd MyApp

# dotnet build
dotnet run

Extra fixes

Below are extra fixes and their manual test steps:

1. unit test

dotnet new winui utApp
cd utApp
dotnet run

after fix: successful launch, no error.

2. winui-dialog

dotnet new winui -n DialogHost
cd DialogHost
dotnet new winui-dialog -n MyConfirmDialog --project DialogHost.csproj

(manually) add a button to demo the new dialog item

in MainPage.xaml:

    <Grid>
        <Button x:Name="ShowDialogButton"
                Content="Show dialog"
                Click="ShowDialogButton_Click"
                HorizontalAlignment="Center"
                VerticalAlignment="Center" />
    </Grid>

in MainPage.xaml.cs:

using Microsoft.UI.Xaml;

    private async void ShowDialogButton_Click(object sender, RoutedEventArgs e)
    {
        var dialog = new MyConfirmDialog
        {
            XamlRoot = this.XamlRoot,
        };
        await dialog.ShowAsync();
    }

run

dotnet run

after fix: successful launch, no error.
clicking the button shows the new dialog item.

3. winui-templatedcontrol

dotnet new winui -n TCdemo
cd TCdemo
dotnet new winui-templatedcontrol -n MyBadge --project TCdemo.csproj

after fix: item created with Generic.xaml:

|- MyBadge.cs
|- Themes/
        |- Generic.xaml

Note: When running dotnet new winui-templatedcontrol -n <item name> --project <project name>.csproj, if the Themes/Generic.xaml file already exists, the creation will be blocked with an error as below:

dotnet new winui-templatedcontrol -n MyBadge2 --project test1.csproj

- Creating this template will make changes to existing files:
-  Overwrite   ./Themes/Generic.xaml

- To create the template anyway, run the command with '--force' option:

This issue can be resolved via flag -I false or --IncludeDefaultStyle false, who skips creating the Generic.xaml file. Here is an example command:

dotnet new winui-templatedcontrol -n MyBadge2 --project TCdemo.csproj -I false

The error message is generated by the dotnet template engine, it cannot be modified from the template side.
So we're adding hint to use -I false in comments of the generated code.

4. winui-resw
   After fix: the "Resources" string in output *.resw file won't be replaced by brutal force.

5. winui-tabview
   Fix the caption button overlap.

After fix 5:

Before fix 5:

[DinahK-2SO]

also adding @nmetulev for review

[nmetulev]

Template validation findings (TODO)

⚠️ Note: This validation pass was performed with the help of GitHub Copilot CLI by generating each template, building, and (where applicable) running the resulting app. Please verify each finding before acting on it — Copilot can be wrong about root causes.

I generated and ran every template (winui, winui-mvvm, winui-navview, winui-tabview, winui-lib, winui-unittest, winui-page, winui-window, winui-dialog, winui-usercontrol, winui-templatedcontrol, winui-resourcedictionary, winui-resw). 9 of 13 work cleanly. 4 issues to look at:

🔴 Blockers

1. winui-unittest — won't build out of the box
The generated .csproj has no <PackageReference> entries at all — missing Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools, MSTest.TestFramework, MSTest.TestAdapter, Microsoft.NET.Test.Sdk, and Microsoft.VisualStudio.TestPlatform.TestFramework. Result: 19+ CS0234/CS0246 errors on a fresh dotnet new winui-unittest.

2. winui-dialog — crashes the app at runtime
<ItemName>.xaml is generated with Style="{StaticResource Default<ItemName>Style}", but no such style is defined anywhere. Calling ShowAsync() throws a XAML parse exception and the app crashes. Confirmed by wiring the generated dialog into a fresh winui project and running.
Fix: drop the Style= line from the template, or also generate/ship a default style.

🟡 Quality bugs

3. winui-templatedcontrol — control renders as nothing
Generates <ItemName>.cs setting DefaultStyleKey = typeof(<ItemName>), but does not scaffold a Themes/Generic.xaml with a default Style + ControlTemplate. Builds fine, but the control has no template → no visual at runtime. Surprising for a "templated control" template.

4. winui-resw — wrong type names in resheaders
The <resheader name="reader"> / writer values say System.<ItemName>.ResXResourceReader, System.Windows.Forms, .... Looks like the template parameter token replaced the literal text Resources inside the namespace System.Resources.ResXResourceReader with the user-supplied item name. Should always be System.Resources.ResX{Reader,Writer} regardless of item name. (Doesn't break resgen in practice, but the file is technically broken.)

[nmetulev]

In addition the tabed template titlebar is shorter than the buttons and they overflow on hover

[niels9001]

In addition the tabed template titlebar is shorter than the buttons and they overflow on hover

See #6407 for comments.

We need DefaultContentDialogStyleto ensure the dialog pick ups the modern style from WinUI vs falling back to an OS style that looks dated. The style should be hardcoded thouhgh and NOT be overwritten by generating the template.

There's a potential fix for the captionbuttons overlapping in the TabView template too.