diff --git a/.gitignore b/.gitignore index 50cb25bb4e..7c95614fe3 100644 --- a/.gitignore +++ b/.gitignore @@ -400,3 +400,8 @@ build/override/ # WindowsAppSDK specific files Microsoft.WinUI.AppX.targets !dev/vsix/**/*.pubxml + +# Per-template merged AGENTS.md files (generated at build time by +# dev/Templates/Source/Directory.Build.targets next to the .vstemplate +# so the VS SDK can pack them into the project-template .zip). +dev/Templates/Source/ProjectTemplates/Desktop/CSharp/*/AGENTS.md diff --git a/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/ClassLibrary/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/ClassLibrary/AGENTS.md new file mode 100644 index 0000000000..5f0b6ffe94 --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/ClassLibrary/AGENTS.md @@ -0,0 +1,109 @@ +# WinUI 3 class library + +A WinUI 3 class library — a reusable component (controls, helpers, +services, resources) that other WinUI 3 desktop apps can reference. + +A class library has **no app shell**: no `App.xaml`, no +`Package.appxmanifest`, no entry point. It's consumed by an app project, +which is what gives it identity at runtime. + +## Project layout + +| Path | Purpose | +| ----------------------- | ----------------------------------------------------------------------------- | +| `Class1.cs` | Starter type. Rename it or delete it as you add real types. | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +XAML controls, styles, and resource dictionaries can be added through the +Visual Studio **Add → New Item** dialog (templated control, user control, +resource dictionary, and friends). + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build + +- VS: *Build → Build Solution* (`Ctrl+Shift+B`). +- CLI: `msbuild /restore /p:Configuration=Debug /p:Platform=x64`. +- No Start-Debugging target: class libraries have no entry point. Reference from an app or unit-test project in the same solution. + +See [MSBuild command-line reference](https://learn.microsoft.com/visualstudio/msbuild/msbuild-command-line-reference). + +## Common next steps + +- Add items: *Add → New Item → WinUI* (user controls, templated controls, resource dictionaries, `.resw`). +- Consume from an app project in the same solution: *Add → Project Reference*. +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Library design guide + +- Custom XAML controls: derive from `Control` and ship `Themes/Generic.xaml` (`Default` / `Light` / `HighContrast` resource dictionaries). For composing existing controls, use `UserControl`. + +External guides: + +- [Dependency properties overview](https://learn.microsoft.com/windows/apps/develop/platform/dependency-properties-overview) +- [Microsoft.CodeAnalysis.PublicApiAnalyzers](https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md) — lock the public API surface +- [Create a NuGet package with the dotnet CLI](https://learn.microsoft.com/nuget/create-packages/creating-a-package-dotnet-cli) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyLibrary.Tests`, then `dotnet add reference ../MyLibrary/MyLibrary.csproj`. +- Tests run inside an MSIX, so dependency-property and `INotifyPropertyChanged` plumbing works in test cases. +- API-break detection: [Microsoft.DotNet.ApiCompat.Tool](https://www.nuget.org/packages/Microsoft.DotNet.ApiCompat.Tool). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the Visual Studio Windows App SDK C# project templates.* + +- Update via the Visual Studio Installer (Windows App SDK C# Templates component). +- Browse all WinUI templates: *File → New → Project*, filter by *WinUI*. The parallel CLI templates: `dotnet new list winui`. diff --git a/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/MvvmApp/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/MvvmApp/AGENTS.md new file mode 100644 index 0000000000..8e6f102af4 --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/MvvmApp/AGENTS.md @@ -0,0 +1,116 @@ +# WinUI 3 desktop MVVM app + +A WinUI 3 desktop app pre-wired with the +[CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) +source generators (`ObservableObject`, `[ObservableProperty]`, +`[RelayCommand]`), packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `Frame` that loads `MainPage`. | +| `MainPage.xaml`, `MainPage.xaml.cs` | First page, bound to `MainPageViewModel` via `{x:Bind}`. | +| `ViewModels/MainPageViewModel.cs` | Example view model deriving from `ObservableObject`, using `[ObservableProperty]` and `[RelayCommand]`. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- VS: **F5**. +- CLI: `msbuild /restore /p:Configuration=Debug /p:Platform=x64`. + +See [MSBuild properties for packaging projects](https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-packaging-dot-net#build-the-package-from-the-command-line). + +## Common next steps + +- Add items: *Add → New Item → WinUI*. +- Companion test project: *Add → New Project → WinUI 3 Unit Test Project*. +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- *Add → New Project → Windows Application Packaging Project*, then *Add → Reference* this app project. +- Right-click `.wapproj` → *Publish → Create App Packages*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the Visual Studio Windows App SDK C# project templates.* + +- Update via the Visual Studio Installer (Windows App SDK C# Templates component). +- Browse all WinUI templates: *File → New → Project*, filter by *WinUI*. The parallel CLI templates: `dotnet new list winui`. diff --git a/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/NavigationApp/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/NavigationApp/AGENTS.md new file mode 100644 index 0000000000..acc878c93f --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/NavigationApp/AGENTS.md @@ -0,0 +1,115 @@ +# WinUI 3 desktop app with navigation + +A WinUI 3 desktop app pre-wired with `NavigationView` for top- or side-nav +patterns, packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar`, a `NavigationView`, and a `Frame` (`NavFrame`) that hosts pages. | +| `Pages/HomePage.xaml`, `.xaml.cs` | Default landing page navigated into `NavFrame`. | +| `Pages/AboutPage.xaml`, `.xaml.cs` | About page wired to a `NavigationViewItem`. | +| `Pages/SettingsPage.xaml`, `.xaml.cs` | Settings page wired to the `NavigationView` settings item. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- VS: **F5**. +- CLI: `msbuild /restore /p:Configuration=Debug /p:Platform=x64`. + +See [MSBuild properties for packaging projects](https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-packaging-dot-net#build-the-package-from-the-command-line). + +## Common next steps + +- Add items: *Add → New Item → WinUI*. +- Companion test project: *Add → New Project → WinUI 3 Unit Test Project*. +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- *Add → New Project → Windows Application Packaging Project*, then *Add → Reference* this app project. +- Right-click `.wapproj` → *Publish → Create App Packages*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the Visual Studio Windows App SDK C# project templates.* + +- Update via the Visual Studio Installer (Windows App SDK C# Templates component). +- Browse all WinUI templates: *File → New → Project*, filter by *WinUI*. The parallel CLI templates: `dotnet new list winui`. diff --git a/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/PackagedApp/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/PackagedApp/AGENTS.md new file mode 100644 index 0000000000..4fbd5d80c8 --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/PackagedApp/AGENTS.md @@ -0,0 +1,128 @@ +# WinUI 3 desktop app (two-project packaged) + +A two-project WinUI 3 desktop app: a `.csproj` for code and a `.wapproj` +for MSIX packaging. Built on the Windows App SDK. + +> [!TIP] +> If you're starting a new app, prefer the single-project **WinUI 3 +> desktop app** template — it packages itself directly from the `.csproj`, +> no `.wapproj` required. Use this two-project shape only when you need +> the `.wapproj` indirection (for example, to package multiple processes +> together or to interop with existing `.wapproj`-based build flows). + +## Project layout + +``` +MySolution.sln +├── MyApp/ # The code project +│ ├── App.xaml, App.xaml.cs +│ ├── MainWindow.xaml, MainWindow.xaml.cs +│ ├── Properties/ +│ ├── app.manifest +│ └── MyApp.csproj +└── MyApp.Package/ # The packaging project + ├── Images/ # Tile, splash, store logos + ├── Package.appxmanifest # App identity and capabilities + └── MyApp.Package.wapproj +``` + +The `.wapproj` references the `.csproj` and owns the manifest, visual +assets, and MSIX output. The `.csproj` owns code, XAML, and target +framework. + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- VS: **F5** with the `.wapproj` set as the startup project (builds both projects, deploys loose-layout MSIX, launches via AUMID). +- CLI: `msbuild MyApp.Package\MyApp.Package.wapproj /restore /p:Platform=x64 /p:Configuration=Debug`. +- `dotnet run` does **not** work on `.wapproj`. For a CLI-driven flow, switch to the single-project blank-app template. + +See [MSBuild properties for packaging projects](https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-packaging-dot-net#build-the-package-from-the-command-line) for `.wapproj` flags. + +## Common next steps + +- Edit `Package.appxmanifest` (lives in the `.wapproj`) via the manifest designer or as XML. +- Add a project to the package: right-click `.wapproj` → *Add → Reference*. +- WinUI items go on the **app project**, not the `.wapproj`: *Add → New Item → WinUI*. +- Update SDK: *Manage NuGet Packages* on the app project → *Updates*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## Publish guide + +This two-project shape **is** the redistributable-MSIX shape — the `.wapproj` already owns `Package.appxmanifest`, signing, and bundle config. + +- Right-click `.wapproj` → *Publish → Create App Packages*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the Visual Studio Windows App SDK C# project templates.* + +- Update via the Visual Studio Installer (Windows App SDK C# Templates component). +- Browse all WinUI templates: *File → New → Project*, filter by *WinUI*. The parallel CLI templates: `dotnet new list winui`. diff --git a/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/SingleProjectPackagedApp/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/SingleProjectPackagedApp/AGENTS.md new file mode 100644 index 0000000000..112f79ffce --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/SingleProjectPackagedApp/AGENTS.md @@ -0,0 +1,112 @@ +# WinUI 3 desktop app + +A blank WinUI 3 desktop app packaged as MSIX, built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------- | --------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `Frame` (`RootFrame`) that displays pages. | +| `MainPage.xaml`, `MainPage.xaml.cs` | First page navigated to inside `RootFrame`. Page-level UI goes here. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- VS: **F5**. +- CLI: `msbuild /restore /p:Configuration=Debug /p:Platform=x64`. + +See [MSBuild properties for packaging projects](https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-packaging-dot-net#build-the-package-from-the-command-line). + +## Common next steps + +- Add items: *Add → New Item → WinUI*. +- Companion test project: *Add → New Project → WinUI 3 Unit Test Project*. +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- *Add → New Project → Windows Application Packaging Project*, then *Add → Reference* this app project. +- Right-click `.wapproj` → *Publish → Create App Packages*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the Visual Studio Windows App SDK C# project templates.* + +- Update via the Visual Studio Installer (Windows App SDK C# Templates component). +- Browse all WinUI templates: *File → New → Project*, filter by *WinUI*. The parallel CLI templates: `dotnet new list winui`. diff --git a/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/TabViewApp/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/TabViewApp/AGENTS.md new file mode 100644 index 0000000000..cb829e49b7 --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/TabViewApp/AGENTS.md @@ -0,0 +1,114 @@ +# WinUI 3 desktop app with tabs + +A WinUI 3 desktop app pre-wired with `TabView` for multi-document or +multi-workspace layouts, packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `TabView` whose tabs host `Frame`-based content. | +| `Pages/HomePage.xaml`, `.xaml.cs` | Default page content for the first tab. | +| `Pages/AboutPage.xaml`, `.xaml.cs` | Example secondary page; opened in another tab. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- VS: **F5**. +- CLI: `msbuild /restore /p:Configuration=Debug /p:Platform=x64`. + +See [MSBuild properties for packaging projects](https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-packaging-dot-net#build-the-package-from-the-command-line). + +## Common next steps + +- Add items: *Add → New Item → WinUI*. +- Companion test project: *Add → New Project → WinUI 3 Unit Test Project*. +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- *Add → New Project → Windows Application Packaging Project*, then *Add → Reference* this app project. +- Right-click `.wapproj` → *Publish → Create App Packages*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the Visual Studio Windows App SDK C# project templates.* + +- Update via the Visual Studio Installer (Windows App SDK C# Templates component). +- Browse all WinUI templates: *File → New → Project*, filter by *WinUI*. The parallel CLI templates: `dotnet new list winui`. diff --git a/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/UnitTestApp/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/UnitTestApp/AGENTS.md new file mode 100644 index 0000000000..ec387bcb1e --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/VSIX/Csharp/UnitTestApp/AGENTS.md @@ -0,0 +1,99 @@ +# WinUI 3 unit test project + +A WinUI 3 unit test project — an MSIX-packaged MSTest container that can +exercise WinUI 3 code in-process, with full access to +`Microsoft.UI.Xaml.*` types and a real `DispatcherQueue`. + +The test process is itself a WinUI 3 app (`UnitTestApp.xaml`) that hosts +the MSTest runner. Tests can construct controls, raise events, and await +dispatcher work the way real app code does. + +## Project layout + +| Path | Purpose | +| ------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `UnitTestApp.xaml`, `UnitTestApp.xaml.cs` | Test host application. Bootstraps the MSTest runner. | +| `UnitTestAppWindow.xaml`, `UnitTestAppWindow.xaml.cs` | Hidden window the host application uses for runner UI / dispatcher. | +| `UnitTests.cs` | Starter `[TestClass]` with example `[TestMethod]`s. Add more test classes alongside. | +| `Package.appxmanifest` | Test container identity. MSIX is required so WinUI 3 types can be exercised. | +| `Assets/` | Test container icons and visual assets. | +| `Properties/` | `launchSettings.json` and per-arch publish profiles for the test container. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, MSTest references, and SDK version. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run tests + +- VS: *Test → Test Explorer → Run All Tests*. +- CLI: `dotnet test` (with `--filter "FullyQualifiedName~..."` or `"TestCategory=Smoke"`). + +See [Filter MSTest tests](https://learn.microsoft.com/dotnet/core/testing/selective-unit-tests). + +## Common next steps + +- Add a test class: *Add → Class* — any `.cs` with `[TestClass]` / `[TestMethod]` is discovered by Test Explorer. +- Reference code under test: *Add → Project Reference* (or *Manage NuGet Packages*). +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Writing tests guide + +- Reference code under test: `dotnet add reference ..\MyApp\MyApp.csproj` (or `dotnet add package `). For internal types, add `[assembly: InternalsVisibleTo("MyApp.Tests")]`. +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro) for `[TestMethod]`, `[DataTestMethod]`, `[TestInitialize]`, etc. + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the Visual Studio Windows App SDK C# project templates.* + +- Update via the Visual Studio Installer (Windows App SDK C# Templates component). +- Browse all WinUI templates: *File → New → Project*, filter by *WinUI*. The parallel CLI templates: `dotnet new list winui`. diff --git a/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/blank-app/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/blank-app/AGENTS.md new file mode 100644 index 0000000000..60bd716702 --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/blank-app/AGENTS.md @@ -0,0 +1,112 @@ +# WinUI 3 desktop app + +A blank WinUI 3 desktop app packaged as MSIX, built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------- | --------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `Frame` (`RootFrame`) that displays pages. | +| `MainPage.xaml`, `MainPage.xaml.cs` | First page navigated to inside `RootFrame`. Page-level UI goes here. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- `dotnet build` — compile. +- `dotnet run` — registers a loose-layout MSIX with AUMID activation and launches. No `Add-AppxPackage` / `MakeAppx` / `SignTool` needed. +- If you hit `REGDB_E_CLASSNOTREG` after editing `Package.appxmanifest`: `winapp unregister`, then `dotnet run`. + +See [`Microsoft.Windows.SDK.BuildTools.WinApp`](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.WinApp) for `WinAppRun*` MSBuild properties. + +## Common next steps + +- Add items: `dotnet new winui-page`, `winui-window`, `winui-usercontrol`, `winui-templatedcontrol`, `winui-dialog`, `winui-resourcedictionary`, `winui-resw` (full list: `dotnet new list winui`). +- Companion test project: `dotnet new winui-unittest -n MyApp.Tests`. +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- CLI: `winapp publish` — see [`winapp` CLI](https://github.com/microsoft/WinAppCli). + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the [`Microsoft.WindowsAppSDK.WinUI.CSharp.Templates`](https://www.nuget.org/packages/Microsoft.WindowsAppSDK.WinUI.CSharp.Templates/) dotnet-new template package.* + +- Update: `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates::*` +- List installed: `dotnet new list winui` diff --git a/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/class-library/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/class-library/AGENTS.md new file mode 100644 index 0000000000..bfc57ef6b0 --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/class-library/AGENTS.md @@ -0,0 +1,108 @@ +# WinUI 3 class library + +A WinUI 3 class library — a reusable component (controls, helpers, +services, resources) that other WinUI 3 desktop apps can reference. + +A class library has **no app shell**: no `App.xaml`, no +`Package.appxmanifest`, no entry point. It's consumed by an app project, +which is what gives it identity at runtime. + +## Project layout + +| Path | Purpose | +| ----------------------- | ----------------------------------------------------------------------------- | +| `Class1.cs` | Starter type. Rename it or delete it as you add real types. | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +XAML controls, styles, and resource dictionaries can be added with +`dotnet new winui-templatedcontrol`, `winui-usercontrol`, +`winui-resourcedictionary`, and friends. + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build + +- `dotnet build` — compile. +- No `dotnet run`: class libraries have no entry point. Reference from a WinUI 3 app or unit-test project (`dotnet new winui-unittest`). + +See [Class libraries](https://learn.microsoft.com/dotnet/standard/class-libraries). + +## Common next steps + +- Add items: `dotnet new winui-usercontrol`, `winui-templatedcontrol`, `winui-resourcedictionary`, `winui-resw` (full list: `dotnet new list winui`). +- Consume: `dotnet add reference ../path/to/this.csproj`, or `dotnet pack` and reference the produced `.nupkg`. +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Library design guide + +- Custom XAML controls: derive from `Control` and ship `Themes/Generic.xaml` (`Default` / `Light` / `HighContrast` resource dictionaries). For composing existing controls, use `UserControl`. + +External guides: + +- [Dependency properties overview](https://learn.microsoft.com/windows/apps/develop/platform/dependency-properties-overview) +- [Microsoft.CodeAnalysis.PublicApiAnalyzers](https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md) — lock the public API surface +- [Create a NuGet package with the dotnet CLI](https://learn.microsoft.com/nuget/create-packages/creating-a-package-dotnet-cli) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyLibrary.Tests`, then `dotnet add reference ../MyLibrary/MyLibrary.csproj`. +- Tests run inside an MSIX, so dependency-property and `INotifyPropertyChanged` plumbing works in test cases. +- API-break detection: [Microsoft.DotNet.ApiCompat.Tool](https://www.nuget.org/packages/Microsoft.DotNet.ApiCompat.Tool). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the [`Microsoft.WindowsAppSDK.WinUI.CSharp.Templates`](https://www.nuget.org/packages/Microsoft.WindowsAppSDK.WinUI.CSharp.Templates/) dotnet-new template package.* + +- Update: `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates::*` +- List installed: `dotnet new list winui` diff --git a/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/mvvm-app/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/mvvm-app/AGENTS.md new file mode 100644 index 0000000000..220532d566 --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/mvvm-app/AGENTS.md @@ -0,0 +1,116 @@ +# WinUI 3 desktop MVVM app + +A WinUI 3 desktop app pre-wired with the +[CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) +source generators (`ObservableObject`, `[ObservableProperty]`, +`[RelayCommand]`), packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `Frame` that loads `MainPage`. | +| `MainPage.xaml`, `MainPage.xaml.cs` | First page, bound to `MainPageViewModel` via `{x:Bind}`. | +| `ViewModels/MainPageViewModel.cs` | Example view model deriving from `ObservableObject`, using `[ObservableProperty]` and `[RelayCommand]`. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- `dotnet build` — compile. +- `dotnet run` — registers a loose-layout MSIX with AUMID activation and launches. No `Add-AppxPackage` / `MakeAppx` / `SignTool` needed. +- If you hit `REGDB_E_CLASSNOTREG` after editing `Package.appxmanifest`: `winapp unregister`, then `dotnet run`. + +See [`Microsoft.Windows.SDK.BuildTools.WinApp`](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.WinApp) for `WinAppRun*` MSBuild properties. + +## Common next steps + +- Add items: `dotnet new winui-page`, `winui-window`, `winui-usercontrol`, `winui-templatedcontrol`, `winui-dialog`, `winui-resourcedictionary`, `winui-resw` (full list: `dotnet new list winui`). +- Companion test project: `dotnet new winui-unittest -n MyApp.Tests`. +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- CLI: `winapp publish` — see [`winapp` CLI](https://github.com/microsoft/WinAppCli). + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the [`Microsoft.WindowsAppSDK.WinUI.CSharp.Templates`](https://www.nuget.org/packages/Microsoft.WindowsAppSDK.WinUI.CSharp.Templates/) dotnet-new template package.* + +- Update: `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates::*` +- List installed: `dotnet new list winui` diff --git a/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/navigation-app/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/navigation-app/AGENTS.md new file mode 100644 index 0000000000..d43ae836ac --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/navigation-app/AGENTS.md @@ -0,0 +1,115 @@ +# WinUI 3 desktop app with navigation + +A WinUI 3 desktop app pre-wired with `NavigationView` for top- or side-nav +patterns, packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar`, a `NavigationView`, and a `Frame` (`NavFrame`) that hosts pages. | +| `Pages/HomePage.xaml`, `.xaml.cs` | Default landing page navigated into `NavFrame`. | +| `Pages/AboutPage.xaml`, `.xaml.cs` | About page wired to a `NavigationViewItem`. | +| `Pages/SettingsPage.xaml`, `.xaml.cs` | Settings page wired to the `NavigationView` settings item. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- `dotnet build` — compile. +- `dotnet run` — registers a loose-layout MSIX with AUMID activation and launches. No `Add-AppxPackage` / `MakeAppx` / `SignTool` needed. +- If you hit `REGDB_E_CLASSNOTREG` after editing `Package.appxmanifest`: `winapp unregister`, then `dotnet run`. + +See [`Microsoft.Windows.SDK.BuildTools.WinApp`](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.WinApp) for `WinAppRun*` MSBuild properties. + +## Common next steps + +- Add items: `dotnet new winui-page`, `winui-window`, `winui-usercontrol`, `winui-templatedcontrol`, `winui-dialog`, `winui-resourcedictionary`, `winui-resw` (full list: `dotnet new list winui`). +- Companion test project: `dotnet new winui-unittest -n MyApp.Tests`. +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- CLI: `winapp publish` — see [`winapp` CLI](https://github.com/microsoft/WinAppCli). + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the [`Microsoft.WindowsAppSDK.WinUI.CSharp.Templates`](https://www.nuget.org/packages/Microsoft.WindowsAppSDK.WinUI.CSharp.Templates/) dotnet-new template package.* + +- Update: `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates::*` +- List installed: `dotnet new list winui` diff --git a/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/tabview-app/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/tabview-app/AGENTS.md new file mode 100644 index 0000000000..bb0146d9c7 --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/tabview-app/AGENTS.md @@ -0,0 +1,114 @@ +# WinUI 3 desktop app with tabs + +A WinUI 3 desktop app pre-wired with `TabView` for multi-document or +multi-workspace layouts, packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `TabView` whose tabs host `Frame`-based content. | +| `Pages/HomePage.xaml`, `.xaml.cs` | Default page content for the first tab. | +| `Pages/AboutPage.xaml`, `.xaml.cs` | Example secondary page; opened in another tab. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run + +- `dotnet build` — compile. +- `dotnet run` — registers a loose-layout MSIX with AUMID activation and launches. No `Add-AppxPackage` / `MakeAppx` / `SignTool` needed. +- If you hit `REGDB_E_CLASSNOTREG` after editing `Package.appxmanifest`: `winapp unregister`, then `dotnet run`. + +See [`Microsoft.Windows.SDK.BuildTools.WinApp`](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.WinApp) for `WinAppRun*` MSBuild properties. + +## Common next steps + +- Add items: `dotnet new winui-page`, `winui-window`, `winui-usercontrol`, `winui-templatedcontrol`, `winui-dialog`, `winui-resourcedictionary`, `winui-resw` (full list: `dotnet new list winui`). +- Companion test project: `dotnet new winui-unittest -n MyApp.Tests`. +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). + +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- CLI: `winapp publish` — see [`winapp` CLI](https://github.com/microsoft/WinAppCli). + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). + +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) + +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the [`Microsoft.WindowsAppSDK.WinUI.CSharp.Templates`](https://www.nuget.org/packages/Microsoft.WindowsAppSDK.WinUI.CSharp.Templates/) dotnet-new template package.* + +- Update: `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates::*` +- List installed: `dotnet new list winui` diff --git a/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/unit-test/AGENTS.md b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/unit-test/AGENTS.md new file mode 100644 index 0000000000..7bfd4ccaca --- /dev/null +++ b/dev/Templates/.review-temp/out-of-box-instructions/dotnet-new/unit-test/AGENTS.md @@ -0,0 +1,99 @@ +# WinUI 3 unit test project + +A WinUI 3 unit test project — an MSIX-packaged MSTest container that can +exercise WinUI 3 code in-process, with full access to +`Microsoft.UI.Xaml.*` types and a real `DispatcherQueue`. + +The test process is itself a WinUI 3 app (`UnitTestApp.xaml`) that hosts +the MSTest runner. Tests can construct controls, raise events, and await +dispatcher work the way real app code does. + +## Project layout + +| Path | Purpose | +| ------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `UnitTestApp.xaml`, `UnitTestApp.xaml.cs` | Test host application. Bootstraps the MSTest runner. | +| `UnitTestAppWindow.xaml`, `UnitTestAppWindow.xaml.cs` | Hidden window the host application uses for runner UI / dispatcher. | +| `UnitTests.cs` | Starter `[TestClass]` with example `[TestMethod]`s. Add more test classes alongside. | +| `Package.appxmanifest` | Test container identity. MSIX is required so WinUI 3 types can be exercised. | +| `Assets/` | Test container icons and visual assets. | +| `Properties/` | `launchSettings.json` and per-arch publish profiles for the test container. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, MSTest references, and SDK version. | + +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). + +## Build and run tests + +- `dotnet test` — builds the test container, registers it as a loose-layout MSIX, runs MSTest. +- Filter: `dotnet test --filter "FullyQualifiedName~MyTestClass"` or `... "TestCategory=Smoke"`. + +See [Filter MSTest tests](https://learn.microsoft.com/dotnet/core/testing/selective-unit-tests). + +## Common next steps + +- Add a test class: any `.cs` with `[TestClass]` / `[TestMethod]` is discovered by MSTest. +- Reference code under test: `dotnet add reference ../MyApp/MyApp.csproj` (or `dotnet add package `). +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). + +## Writing tests guide + +- Reference code under test: `dotnet add reference ..\MyApp\MyApp.csproj` (or `dotnet add package `). For internal types, add `[assembly: InternalsVisibleTo("MyApp.Tests")]`. +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro) for `[TestMethod]`, `[DataTestMethod]`, `[TestInitialize]`, etc. + +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). + +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). + +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) + +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) + +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) + +--- + +*Generated from the [`Microsoft.WindowsAppSDK.WinUI.CSharp.Templates`](https://www.nuget.org/packages/Microsoft.WindowsAppSDK.WinUI.CSharp.Templates/) dotnet-new template package.* + +- Update: `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates::*` +- List installed: `dotnet new list winui` diff --git a/dev/Templates/Dotnet/WinAppSdk.CSharp.DotnetNewTemplates.csproj b/dev/Templates/Dotnet/WinAppSdk.CSharp.DotnetNewTemplates.csproj index e432695bf7..ff81777bc4 100644 --- a/dev/Templates/Dotnet/WinAppSdk.CSharp.DotnetNewTemplates.csproj +++ b/dev/Templates/Dotnet/WinAppSdk.CSharp.DotnetNewTemplates.csproj @@ -42,6 +42,23 @@ <_GitignoreSource>templates\gitignore.txt + + + <_SectionsDir>$([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)..\Source\TemplateReadmeSections')) + + + GitignoreSource="$([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)$(_GitignoreSource)'))" + SectionsDir="$(_SectionsDir)" + MergedReadmeDir="$(IntermediateOutputPath)merged-readmes\"> diff --git a/dev/Templates/Dotnet/templates/blank-app/AGENTS.md b/dev/Templates/Dotnet/templates/blank-app/AGENTS.md new file mode 100644 index 0000000000..1d4c167321 --- /dev/null +++ b/dev/Templates/Dotnet/templates/blank-app/AGENTS.md @@ -0,0 +1,42 @@ +# WinUI 3 desktop app + +A blank WinUI 3 desktop app packaged as MSIX, built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------- | --------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `Frame` (`RootFrame`) that displays pages. | +| `MainPage.xaml`, `MainPage.xaml.cs` | First page navigated to inside `RootFrame`. Page-level UI goes here. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +####Prerequisites.md#### + +####BuildAndRun.app.dotnet.md#### + +####CommonNextSteps.app.dotnet.md#### + +####PublishGuide.app.dotnet.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.dotnet.md#### diff --git a/dev/Templates/Dotnet/templates/class-library/AGENTS.md b/dev/Templates/Dotnet/templates/class-library/AGENTS.md new file mode 100644 index 0000000000..ae00f816a1 --- /dev/null +++ b/dev/Templates/Dotnet/templates/class-library/AGENTS.md @@ -0,0 +1,43 @@ +# WinUI 3 class library + +A WinUI 3 class library — a reusable component (controls, helpers, +services, resources) that other WinUI 3 desktop apps can reference. + +A class library has **no app shell**: no `App.xaml`, no +`Package.appxmanifest`, no entry point. It's consumed by an app project, +which is what gives it identity at runtime. + +## Project layout + +| Path | Purpose | +| ----------------------- | ----------------------------------------------------------------------------- | +| `Class1.cs` | Starter type. Rename it or delete it as you add real types. | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +XAML controls, styles, and resource dictionaries can be added with +`dotnet new winui-templatedcontrol`, `winui-usercontrol`, +`winui-resourcedictionary`, and friends. + +####Prerequisites.md#### + +####BuildAndRun.library.dotnet.md#### + +####CommonNextSteps.library.dotnet.md#### + +####AppArchitectureGuide.library.md#### + +####TestingGuide.library.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.dotnet.md#### diff --git a/dev/Templates/Dotnet/templates/mvvm-app/AGENTS.md b/dev/Templates/Dotnet/templates/mvvm-app/AGENTS.md new file mode 100644 index 0000000000..1f633107e3 --- /dev/null +++ b/dev/Templates/Dotnet/templates/mvvm-app/AGENTS.md @@ -0,0 +1,46 @@ +# WinUI 3 desktop MVVM app + +A WinUI 3 desktop app pre-wired with the +[CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) +source generators (`ObservableObject`, `[ObservableProperty]`, +`[RelayCommand]`), packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `Frame` that loads `MainPage`. | +| `MainPage.xaml`, `MainPage.xaml.cs` | First page, bound to `MainPageViewModel` via `{x:Bind}`. | +| `ViewModels/MainPageViewModel.cs` | Example view model deriving from `ObservableObject`, using `[ObservableProperty]` and `[RelayCommand]`. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +####Prerequisites.md#### + +####BuildAndRun.app.dotnet.md#### + +####CommonNextSteps.app.dotnet.md#### + +####PublishGuide.app.dotnet.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.dotnet.md#### diff --git a/dev/Templates/Dotnet/templates/navigation-app/AGENTS.md b/dev/Templates/Dotnet/templates/navigation-app/AGENTS.md new file mode 100644 index 0000000000..f96786de4d --- /dev/null +++ b/dev/Templates/Dotnet/templates/navigation-app/AGENTS.md @@ -0,0 +1,45 @@ +# WinUI 3 desktop app with navigation + +A WinUI 3 desktop app pre-wired with `NavigationView` for top- or side-nav +patterns, packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar`, a `NavigationView`, and a `Frame` (`NavFrame`) that hosts pages. | +| `Pages/HomePage.xaml`, `.xaml.cs` | Default landing page navigated into `NavFrame`. | +| `Pages/AboutPage.xaml`, `.xaml.cs` | About page wired to a `NavigationViewItem`. | +| `Pages/SettingsPage.xaml`, `.xaml.cs` | Settings page wired to the `NavigationView` settings item. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +####Prerequisites.md#### + +####BuildAndRun.app.dotnet.md#### + +####CommonNextSteps.app.dotnet.md#### + +####PublishGuide.app.dotnet.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.dotnet.md#### diff --git a/dev/Templates/Dotnet/templates/tabview-app/AGENTS.md b/dev/Templates/Dotnet/templates/tabview-app/AGENTS.md new file mode 100644 index 0000000000..c5725b764c --- /dev/null +++ b/dev/Templates/Dotnet/templates/tabview-app/AGENTS.md @@ -0,0 +1,44 @@ +# WinUI 3 desktop app with tabs + +A WinUI 3 desktop app pre-wired with `TabView` for multi-document or +multi-workspace layouts, packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `TabView` whose tabs host `Frame`-based content. | +| `Pages/HomePage.xaml`, `.xaml.cs` | Default page content for the first tab. | +| `Pages/AboutPage.xaml`, `.xaml.cs` | Example secondary page; opened in another tab. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +####Prerequisites.md#### + +####BuildAndRun.app.dotnet.md#### + +####CommonNextSteps.app.dotnet.md#### + +####PublishGuide.app.dotnet.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.dotnet.md#### diff --git a/dev/Templates/Dotnet/templates/unit-test/AGENTS.md b/dev/Templates/Dotnet/templates/unit-test/AGENTS.md new file mode 100644 index 0000000000..0b74f74222 --- /dev/null +++ b/dev/Templates/Dotnet/templates/unit-test/AGENTS.md @@ -0,0 +1,44 @@ +# WinUI 3 unit test project + +A WinUI 3 unit test project — an MSIX-packaged MSTest container that can +exercise WinUI 3 code in-process, with full access to +`Microsoft.UI.Xaml.*` types and a real `DispatcherQueue`. + +The test process is itself a WinUI 3 app (`UnitTestApp.xaml`) that hosts +the MSTest runner. Tests can construct controls, raise events, and await +dispatcher work the way real app code does. + +## Project layout + +| Path | Purpose | +| ------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `UnitTestApp.xaml`, `UnitTestApp.xaml.cs` | Test host application. Bootstraps the MSTest runner. | +| `UnitTestAppWindow.xaml`, `UnitTestAppWindow.xaml.cs` | Hidden window the host application uses for runner UI / dispatcher. | +| `UnitTests.cs` | Starter `[TestClass]` with example `[TestMethod]`s. Add more test classes alongside. | +| `Package.appxmanifest` | Test container identity. MSIX is required so WinUI 3 types can be exercised. | +| `Assets/` | Test container icons and visual assets. | +| `Properties/` | `launchSettings.json` and per-arch publish profiles for the test container. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, MSTest references, and SDK version. | + +####Prerequisites.md#### + +####BuildAndRun.unittest.dotnet.md#### + +####CommonNextSteps.unittest.dotnet.md#### + +####TestingGuide.unittest.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.dotnet.md#### diff --git a/dev/Templates/Generate-ReviewArtifacts.ps1 b/dev/Templates/Generate-ReviewArtifacts.ps1 new file mode 100644 index 0000000000..50340bf1d5 --- /dev/null +++ b/dev/Templates/Generate-ReviewArtifacts.ps1 @@ -0,0 +1,137 @@ +<# +.SYNOPSIS + Stages every merged AGENTS.md (dotnet-new + VSIX) under + dev\Templates\.review-temp for human review on a PR. + +.DESCRIPTION + Reuses Source\Validate-VSIXBuilds.ps1 to build the 7 VSIX twin csprojs; + that fires the _GenerateMergedReadme target and writes the merged + AGENTS.md next to each .vstemplate. Then packs + Dotnet\WinAppSdk.CSharp.DotnetNewTemplates.csproj, which fires the + inline ExpandProjectTemplatePackItems task and writes merged AGENTS.md + files into obj\\net8.0\merged-readmes\\AGENTS.md. + + Both sets are copied into a single review tree: + dev\Templates\.review-temp\out-of-box-instructions\ + dotnet-new\\AGENTS.md (e.g. blank-app) + VSIX\Csharp\\AGENTS.md (e.g. ClassLibrary) + + This output is for PR review only. It is intended to be deleted from + the branch before the PR merges -- the merged files themselves are + generated at build/pack time and never need to live in tree. + + Re-running the script wipes and refreshes .review-temp\. + +.PARAMETER Configuration + MSBuild configuration to use for the dotnet pack. The dot-sourced + Validate-VSIXBuilds.ps1 always builds Release; passing anything else + here only affects the dotnet pack output path. Default: Release. +#> +[CmdletBinding()] +param( + [string]$Configuration = "Release" +) + +$ErrorActionPreference = "Stop" + +$TemplatesDir = $PSScriptRoot +$RepoRoot = (Resolve-Path (Join-Path $TemplatesDir "..\..")).Path +$ReviewRoot = Join-Path $TemplatesDir ".review-temp\out-of-box-instructions" +$VsixDest = Join-Path $ReviewRoot "VSIX\Csharp" +$DotnetDest = Join-Path $ReviewRoot "dotnet-new" + +# --- 1. Clean previous output so reviewers see exactly what this run produced. --- +if (Test-Path $ReviewRoot) { + Remove-Item -LiteralPath $ReviewRoot -Recurse -Force +} +New-Item -ItemType Directory -Path $VsixDest, $DotnetDest -Force | Out-Null + +# --- 2. VSIX: dot-source the validation script so it builds the 7 twin csprojs +# in our scope. That sets $msbuild, $projects, $agents, $overallPass for us. --- +$validateScript = Join-Path $TemplatesDir "Source\Validate-VSIXBuilds.ps1" +Push-Location $RepoRoot +try { + . $validateScript +} +finally { + Pop-Location +} +if (-not $overallPass) { + throw "VSIX validation failed before staging artifacts: $firstFailure" +} + +# --- 3. Stage VSIX merged AGENTS.md files. --- +# All 7 VSIX twin csprojs set , so each one produces a merged +# file next to its .vstemplate. PackagedApp is a ProjectGroup umbrella whose +# .vstemplate does not AGENTS.md, so its merged file is generated +# but never shipped in the .vsix; we include it for review completeness. +$vsixNames = @( + "ClassLibrary", + "MvvmApp", + "NavigationApp", + "PackagedApp", + "SingleProjectPackagedApp", + "TabViewApp", + "UnitTestApp" +) +foreach ($name in $vsixNames) { + $src = Join-Path $RepoRoot "dev\Templates\Source\ProjectTemplates\Desktop\CSharp\$name\AGENTS.md" + if (-not (Test-Path $src)) { + Write-Warning "VSIX merged AGENTS.md not generated for $name; skipping." + continue + } + $dstDir = Join-Path $VsixDest $name + New-Item -ItemType Directory -Path $dstDir -Force | Out-Null + Copy-Item -LiteralPath $src -Destination (Join-Path $dstDir "AGENTS.md") -Force + Write-Host "Staged VSIX\Csharp\$name\AGENTS.md" +} + +# --- 4. dotnet-new: pack the templates csproj to fire ExpandProjectTemplatePackItems. --- +$dotnetProj = Join-Path $RepoRoot "dev\Templates\Dotnet\WinAppSdk.CSharp.DotnetNewTemplates.csproj" +Write-Host "" +Write-Host "Packing $dotnetProj ..." +& $msbuild $dotnetProj /t:Pack /p:Configuration=$Configuration /v:minimal /nologo +if ($LASTEXITCODE -ne 0) { + throw "dotnet templates Pack failed (exit $LASTEXITCODE)." +} + +# --- 5. Build a short-id -> friendly folder name map from templates.props. --- +# The merge task writes merged AGENTS.md into merged-readmes\\ where +# ItemSpec is the short id (e.g. winui.blankapp). The user-facing review folder +# uses the friendly DotnetConfigDir leaf name (e.g. blank-app) instead. +$propsPath = Join-Path $TemplatesDir "templates.props" +[xml]$propsXml = Get-Content -LiteralPath $propsPath -Raw +$shortToFriendly = @{} +foreach ($pt in $propsXml.SelectNodes("//ProjectTemplate[@Include]")) { + $configNode = $pt.SelectSingleNode("DotnetConfigDir") + if (-not $configNode) { continue } + $configDir = $configNode.InnerText.Trim() + if ([string]::IsNullOrWhiteSpace($configDir)) { continue } + $shortToFriendly[$pt.GetAttribute("Include")] = (Split-Path $configDir -Leaf) +} + +# --- 6. Stage dotnet-new merged AGENTS.md files. --- +$mergedRoot = Join-Path $RepoRoot "dev\Templates\Dotnet\obj\$Configuration\net8.0\merged-readmes" +if (-not (Test-Path $mergedRoot)) { + throw "merged-readmes directory missing at $mergedRoot after Pack." +} +foreach ($itemDir in Get-ChildItem -LiteralPath $mergedRoot -Directory) { + $src = Join-Path $itemDir.FullName "AGENTS.md" + if (-not (Test-Path $src)) { continue } + + $shortId = $itemDir.Name + $friendly = $shortToFriendly[$shortId] + if (-not $friendly) { + Write-Warning "No DotnetConfigDir mapping for short id '$shortId'; using id as folder name." + $friendly = $shortId + } + + $dstDir = Join-Path $DotnetDest $friendly + New-Item -ItemType Directory -Path $dstDir -Force | Out-Null + Copy-Item -LiteralPath $src -Destination (Join-Path $dstDir "AGENTS.md") -Force + Write-Host "Staged dotnet-new\$friendly\AGENTS.md" +} + +Write-Host "" +Write-Host "Review artifacts staged under:" +Write-Host " $ReviewRoot" diff --git a/dev/Templates/Source/Directory.Build.targets b/dev/Templates/Source/Directory.Build.targets new file mode 100644 index 0000000000..cd2682ba48 --- /dev/null +++ b/dev/Templates/Source/Directory.Build.targets @@ -0,0 +1,115 @@ + + + + + + $([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)TemplateReadmeSections')) + $(MSBuildProjectDirectory)\AGENTS.md + + + + + + + + + + + + + + + +{ + string fileName = m.Groups[1].Value; + string sectionPath = Path.Combine(SectionsDir, fileName); + if (!File.Exists(sectionPath)) + { + Log.LogError( + "Outline '{0}' references section file '{1}' but '{2}' does not exist.", + TemplateReadme, fileName, sectionPath); + hadMissing = true; + return m.Value; + } + return File.ReadAllText(sectionPath).TrimEnd(); +}); +if (hadMissing) { return false; } + +// Collapse 3+ consecutive newlines down to a single blank-line separator +// and normalize trailing whitespace. +merged = Regex.Replace(merged, @"(\r?\n){3,}", "\n\n").TrimEnd() + "\n"; + +// Any unresolved ####...#### markers left over indicate a malformed placeholder +// in the outline -- fail loudly so we never ship a README with literal markers. +var leftovers = Regex.Matches(merged, "####[^#]+####"); +if (leftovers.Count > 0) +{ + var names = new HashSet(StringComparer.Ordinal); + foreach (Match m in leftovers) { names.Add(m.Value); } + Log.LogError( + "Merged README still contains unresolved markers: {0}. " + + "Placeholders must have the form ####FileName.md#### where FileName.md is a real file in '{1}'.", + string.Join(", ", names), SectionsDir); + return false; +} + +Directory.CreateDirectory(Path.GetDirectoryName(OutputPath)); + +// Skip rewriting unchanged content so we don't churn the file's timestamp on every build. +if (!File.Exists(OutputPath) || File.ReadAllText(OutputPath) != merged) +{ + File.WriteAllText(OutputPath, merged); +} +]]> + + + + + + + + + + + + diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.csproj b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.csproj index 459712483b..bfbc3b37b4 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.csproj +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.csproj @@ -27,6 +27,10 @@ false false SHA256 + + $(MSBuildThisFileDirectory)..\..\..\..\..\VSIX\templates\Desktop\CSharp\ClassLibrary\AGENTS.md true diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.vstemplate b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.vstemplate index 2ba36f6d5c..c30ad77a6b 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.vstemplate +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.vstemplate @@ -26,6 +26,7 @@ Class1.cs + AGENTS.md diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.csproj b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.csproj index ce99462535..d644188070 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.csproj +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.csproj @@ -27,6 +27,10 @@ false false SHA256 + + $(MSBuildThisFileDirectory)..\..\..\..\..\VSIX\templates\Desktop\CSharp\MvvmApp\AGENTS.md true diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.vstemplate b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.vstemplate index 57bca3d069..e532286d83 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.vstemplate +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.vstemplate @@ -42,6 +42,7 @@ MainPage.xaml MainPage.xaml.cs Package-managed.appxmanifest + AGENTS.md MainPageViewModel.cs diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.csproj b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.csproj index de1bc9cf8c..b2cb341029 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.csproj +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.csproj @@ -27,6 +27,10 @@ false false SHA256 + + $(MSBuildThisFileDirectory)..\..\..\..\..\VSIX\templates\Desktop\CSharp\NavigationApp\AGENTS.md true diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.vstemplate b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.vstemplate index 9e4ad75d31..8ce3c07add 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.vstemplate +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.vstemplate @@ -40,6 +40,7 @@ MainWindow.xaml MainWindow.xaml.cs Package-managed.appxmanifest + AGENTS.md HomePage.xaml HomePage.xaml.cs diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/PackagedApp/WinUI.Desktop.Cs.PackagedApp.csproj b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/PackagedApp/WinUI.Desktop.Cs.PackagedApp.csproj index b27444729e..e4773545ed 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/PackagedApp/WinUI.Desktop.Cs.PackagedApp.csproj +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/PackagedApp/WinUI.Desktop.Cs.PackagedApp.csproj @@ -27,6 +27,13 @@ false false SHA256 + + $(MSBuildThisFileDirectory)..\..\..\..\..\VSIX\templates\Desktop\CSharp\PackagedApp\AGENTS.md true diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.csproj b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.csproj index 9641aaf7f3..d21efe602b 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.csproj +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.csproj @@ -27,6 +27,11 @@ false false SHA256 + + $(MSBuildThisFileDirectory)..\..\..\..\..\VSIX\templates\Desktop\CSharp\SingleProjectPackagedApp\AGENTS.md true diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.vstemplate b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.vstemplate index 7690fc7da9..a8c961f00f 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.vstemplate +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.vstemplate @@ -42,6 +42,7 @@ MainPage.xaml MainPage.xaml.cs Package-managed.appxmanifest + AGENTS.md SplashScreen.scale-200.png LockScreenLogo.scale-200.png diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.csproj b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.csproj index c5979d7301..8a0ba7f4fb 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.csproj +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.csproj @@ -27,6 +27,10 @@ false false SHA256 + + $(MSBuildThisFileDirectory)..\..\..\..\..\VSIX\templates\Desktop\CSharp\TabViewApp\AGENTS.md true diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.vstemplate b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.vstemplate index 2b300d62ee..a8c1b6a7bb 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.vstemplate +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.vstemplate @@ -40,6 +40,7 @@ MainWindow.xaml MainWindow.xaml.cs Package-managed.appxmanifest + AGENTS.md HomePage.xaml HomePage.xaml.cs diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.csproj b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.csproj index 173cdd8a37..7e7892c189 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.csproj +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.csproj @@ -27,6 +27,10 @@ false false SHA256 + + $(MSBuildThisFileDirectory)..\..\..\..\..\VSIX\templates\Desktop\CSharp\UnitTestApp\AGENTS.md true diff --git a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.vstemplate b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.vstemplate index d5fb8f612a..c75154bbae 100644 --- a/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.vstemplate +++ b/dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.vstemplate @@ -40,6 +40,7 @@ UnitTestAppWindow.xaml.cs UnitTests.cs Package-managed.appxmanifest + AGENTS.md SplashScreen.scale-200.png LockScreenLogo.scale-200.png diff --git a/dev/Templates/Source/TemplateReadmeSections/AccessibilityGuide.md b/dev/Templates/Source/TemplateReadmeSections/AccessibilityGuide.md new file mode 100644 index 0000000000..ed2c749362 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/AccessibilityGuide.md @@ -0,0 +1,7 @@ +## Accessibility guide + +External guides: + +- [Accessibility in Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-overview) + +Tooling: [Accessibility Insights for Windows](https://accessibilityinsights.io/docs/windows/overview/). diff --git a/dev/Templates/Source/TemplateReadmeSections/AppArchitectureGuide.library.md b/dev/Templates/Source/TemplateReadmeSections/AppArchitectureGuide.library.md new file mode 100644 index 0000000000..ee749cc37c --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/AppArchitectureGuide.library.md @@ -0,0 +1,9 @@ +## Library design guide + +- Custom XAML controls: derive from `Control` and ship `Themes/Generic.xaml` (`Default` / `Light` / `HighContrast` resource dictionaries). For composing existing controls, use `UserControl`. + +External guides: + +- [Dependency properties overview](https://learn.microsoft.com/windows/apps/develop/platform/dependency-properties-overview) +- [Microsoft.CodeAnalysis.PublicApiAnalyzers](https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md) — lock the public API surface +- [Create a NuGet package with the dotnet CLI](https://learn.microsoft.com/nuget/create-packages/creating-a-package-dotnet-cli) diff --git a/dev/Templates/Source/TemplateReadmeSections/AppArchitectureGuide.md b/dev/Templates/Source/TemplateReadmeSections/AppArchitectureGuide.md new file mode 100644 index 0000000000..b64d3a5434 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/AppArchitectureGuide.md @@ -0,0 +1,8 @@ +## App architecture guide + +External guides: + +- [MVVM pattern](https://learn.microsoft.com/dotnet/architecture/maui/mvvm) +- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) — source generators for properties and commands +- [Navigation design basics](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics) — `Frame.Navigate`, `NavigationCacheMode` +- [Async/await in WinUI](https://learn.microsoft.com/windows/apps/develop/threading-async/) diff --git a/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.app.dotnet.md b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.app.dotnet.md new file mode 100644 index 0000000000..050fa8a4a0 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.app.dotnet.md @@ -0,0 +1,7 @@ +## Build and run + +- `dotnet build` — compile. +- `dotnet run` — registers a loose-layout MSIX with AUMID activation and launches. No `Add-AppxPackage` / `MakeAppx` / `SignTool` needed. +- If you hit `REGDB_E_CLASSNOTREG` after editing `Package.appxmanifest`: `winapp unregister`, then `dotnet run`. + +See [`Microsoft.Windows.SDK.BuildTools.WinApp`](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools.WinApp) for `WinAppRun*` MSBuild properties. diff --git a/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.app.vsix.md b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.app.vsix.md new file mode 100644 index 0000000000..01bba53acd --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.app.vsix.md @@ -0,0 +1,6 @@ +## Build and run + +- VS: **F5**. +- CLI: `msbuild /restore /p:Configuration=Debug /p:Platform=x64`. + +See [MSBuild properties for packaging projects](https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-packaging-dot-net#build-the-package-from-the-command-line). diff --git a/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.library.dotnet.md b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.library.dotnet.md new file mode 100644 index 0000000000..34d53e2638 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.library.dotnet.md @@ -0,0 +1,6 @@ +## Build + +- `dotnet build` — compile. +- No `dotnet run`: class libraries have no entry point. Reference from a WinUI 3 app or unit-test project (`dotnet new winui-unittest`). + +See [Class libraries](https://learn.microsoft.com/dotnet/standard/class-libraries). diff --git a/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.library.vsix.md b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.library.vsix.md new file mode 100644 index 0000000000..c29b776d66 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.library.vsix.md @@ -0,0 +1,7 @@ +## Build + +- VS: *Build → Build Solution* (`Ctrl+Shift+B`). +- CLI: `msbuild /restore /p:Configuration=Debug /p:Platform=x64`. +- No Start-Debugging target: class libraries have no entry point. Reference from an app or unit-test project in the same solution. + +See [MSBuild command-line reference](https://learn.microsoft.com/visualstudio/msbuild/msbuild-command-line-reference). diff --git a/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.unittest.dotnet.md b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.unittest.dotnet.md new file mode 100644 index 0000000000..ece9983ecf --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.unittest.dotnet.md @@ -0,0 +1,6 @@ +## Build and run tests + +- `dotnet test` — builds the test container, registers it as a loose-layout MSIX, runs MSTest. +- Filter: `dotnet test --filter "FullyQualifiedName~MyTestClass"` or `... "TestCategory=Smoke"`. + +See [Filter MSTest tests](https://learn.microsoft.com/dotnet/core/testing/selective-unit-tests). diff --git a/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.unittest.vsix.md b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.unittest.vsix.md new file mode 100644 index 0000000000..b2a3dc62d0 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.unittest.vsix.md @@ -0,0 +1,6 @@ +## Build and run tests + +- VS: *Test → Test Explorer → Run All Tests*. +- CLI: `dotnet test` (with `--filter "FullyQualifiedName~..."` or `"TestCategory=Smoke"`). + +See [Filter MSTest tests](https://learn.microsoft.com/dotnet/core/testing/selective-unit-tests). diff --git a/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.wapproj.vsix.md b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.wapproj.vsix.md new file mode 100644 index 0000000000..4e5b51baf2 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/BuildAndRun.wapproj.vsix.md @@ -0,0 +1,7 @@ +## Build and run + +- VS: **F5** with the `.wapproj` set as the startup project (builds both projects, deploys loose-layout MSIX, launches via AUMID). +- CLI: `msbuild MyApp.Package\MyApp.Package.wapproj /restore /p:Platform=x64 /p:Configuration=Debug`. +- `dotnet run` does **not** work on `.wapproj`. For a CLI-driven flow, switch to the single-project blank-app template. + +See [MSBuild properties for packaging projects](https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-packaging-dot-net#build-the-package-from-the-command-line) for `.wapproj` flags. diff --git a/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.app.dotnet.md b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.app.dotnet.md new file mode 100644 index 0000000000..24a37de091 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.app.dotnet.md @@ -0,0 +1,7 @@ +## Common next steps + +- Add items: `dotnet new winui-page`, `winui-window`, `winui-usercontrol`, `winui-templatedcontrol`, `winui-dialog`, `winui-resourcedictionary`, `winui-resw` (full list: `dotnet new list winui`). +- Companion test project: `dotnet new winui-unittest -n MyApp.Tests`. +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). diff --git a/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.app.vsix.md b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.app.vsix.md new file mode 100644 index 0000000000..5733bc8e00 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.app.vsix.md @@ -0,0 +1,7 @@ +## Common next steps + +- Add items: *Add → New Item → WinUI*. +- Companion test project: *Add → New Project → WinUI 3 Unit Test Project*. +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). diff --git a/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.library.dotnet.md b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.library.dotnet.md new file mode 100644 index 0000000000..e1996f5965 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.library.dotnet.md @@ -0,0 +1,7 @@ +## Common next steps + +- Add items: `dotnet new winui-usercontrol`, `winui-templatedcontrol`, `winui-resourcedictionary`, `winui-resw` (full list: `dotnet new list winui`). +- Consume: `dotnet add reference ../path/to/this.csproj`, or `dotnet pack` and reference the produced `.nupkg`. +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). diff --git a/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.library.vsix.md b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.library.vsix.md new file mode 100644 index 0000000000..44303adb59 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.library.vsix.md @@ -0,0 +1,7 @@ +## Common next steps + +- Add items: *Add → New Item → WinUI* (user controls, templated controls, resource dictionaries, `.resw`). +- Consume from an app project in the same solution: *Add → Project Reference*. +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [WinUI 3 docs](https://learn.microsoft.com/windows/apps/winui/winui3/). diff --git a/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.unittest.dotnet.md b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.unittest.dotnet.md new file mode 100644 index 0000000000..fab966f0bc --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.unittest.dotnet.md @@ -0,0 +1,7 @@ +## Common next steps + +- Add a test class: any `.cs` with `[TestClass]` / `[TestMethod]` is discovered by MSTest. +- Reference code under test: `dotnet add reference ../MyApp/MyApp.csproj` (or `dotnet add package `). +- Update SDK: `dotnet add package Microsoft.WindowsAppSDK`. + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). diff --git a/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.unittest.vsix.md b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.unittest.vsix.md new file mode 100644 index 0000000000..af925b1693 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.unittest.vsix.md @@ -0,0 +1,7 @@ +## Common next steps + +- Add a test class: *Add → Class* — any `.cs` with `[TestClass]` / `[TestMethod]` is discovered by Test Explorer. +- Reference code under test: *Add → Project Reference* (or *Manage NuGet Packages*). +- Update SDK: *Manage NuGet Packages → Updates → Microsoft.WindowsAppSDK*. + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). diff --git a/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.wapproj.vsix.md b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.wapproj.vsix.md new file mode 100644 index 0000000000..7f17ff5998 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/CommonNextSteps.wapproj.vsix.md @@ -0,0 +1,8 @@ +## Common next steps + +- Edit `Package.appxmanifest` (lives in the `.wapproj`) via the manifest designer or as XML. +- Add a project to the package: right-click `.wapproj` → *Add → Reference*. +- WinUI items go on the **app project**, not the `.wapproj`: *Add → New Item → WinUI*. +- Update SDK: *Manage NuGet Packages* on the app project → *Updates*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). diff --git a/dev/Templates/Source/TemplateReadmeSections/DocumentationGuide.md b/dev/Templates/Source/TemplateReadmeSections/DocumentationGuide.md new file mode 100644 index 0000000000..e19f50c563 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/DocumentationGuide.md @@ -0,0 +1,9 @@ +## Documentation and samples + +- [Windows App SDK documentation](https://learn.microsoft.com/windows/apps/windows-app-sdk/) +- [WinUI 3 API reference](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/) +- [Windows Platform SDK API reference](https://learn.microsoft.com/uwp/api/) — `Windows.*` WinRT APIs (file pickers, geolocation, sensors, clipboard, …) not covered by WinUI 3. +- [Windows App SDK samples](https://github.com/microsoft/WindowsAppSDK-Samples) +- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) — control showcase +- [AI Dev Gallery](https://github.com/microsoft/ai-dev-gallery) — on-device AI/ML patterns +- [`winapp` CLI](https://github.com/microsoft/WinAppCli) diff --git a/dev/Templates/Source/TemplateReadmeSections/FrameworkFooter.dotnet.md b/dev/Templates/Source/TemplateReadmeSections/FrameworkFooter.dotnet.md new file mode 100644 index 0000000000..4ec252a83a --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/FrameworkFooter.dotnet.md @@ -0,0 +1,4 @@ +*Generated from the [`Microsoft.WindowsAppSDK.WinUI.CSharp.Templates`](https://www.nuget.org/packages/Microsoft.WindowsAppSDK.WinUI.CSharp.Templates/) dotnet-new template package.* + +- Update: `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates::*` +- List installed: `dotnet new list winui` diff --git a/dev/Templates/Source/TemplateReadmeSections/FrameworkFooter.vsix.md b/dev/Templates/Source/TemplateReadmeSections/FrameworkFooter.vsix.md new file mode 100644 index 0000000000..46ef00ccdd --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/FrameworkFooter.vsix.md @@ -0,0 +1,4 @@ +*Generated from the Visual Studio Windows App SDK C# project templates.* + +- Update via the Visual Studio Installer (Windows App SDK C# Templates component). +- Browse all WinUI templates: *File → New → Project*, filter by *WinUI*. The parallel CLI templates: `dotnet new list winui`. diff --git a/dev/Templates/Source/TemplateReadmeSections/GlobalizationGuide.md b/dev/Templates/Source/TemplateReadmeSections/GlobalizationGuide.md new file mode 100644 index 0000000000..1de4aab15f --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/GlobalizationGuide.md @@ -0,0 +1,6 @@ +## Globalization guide + +External guides: + +- [Globalize your WinUI app](https://learn.microsoft.com/windows/apps/design/globalizing/guidelines-and-checklist-for-globalizing-your-app) +- [Localize strings with the Resource Management System](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/localize-strings) diff --git a/dev/Templates/Source/TemplateReadmeSections/PerformanceGuide.md b/dev/Templates/Source/TemplateReadmeSections/PerformanceGuide.md new file mode 100644 index 0000000000..f92935b963 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/PerformanceGuide.md @@ -0,0 +1,9 @@ +## Performance guide + +External guides: + +- [`{x:Bind}` markup extension](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-bind-markup-extension) — compiled bindings +- [`x:Load` attribute](https://learn.microsoft.com/windows/apps/develop/platform/xaml/x-load-attribute) — deferred UI +- [Windows app performance overview](https://learn.microsoft.com/windows/apps/performance/) + +Profilers: [Visual Studio Performance Profiler](https://learn.microsoft.com/visualstudio/profiling/), [PerfView](https://github.com/microsoft/perfview). diff --git a/dev/Templates/Source/TemplateReadmeSections/Prerequisites.md b/dev/Templates/Source/TemplateReadmeSections/Prerequisites.md new file mode 100644 index 0000000000..3de71410c6 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/Prerequisites.md @@ -0,0 +1,3 @@ +## Prerequisites + +See [Set up your dev environment for Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment). diff --git a/dev/Templates/Source/TemplateReadmeSections/PublishGuide.app.dotnet.md b/dev/Templates/Source/TemplateReadmeSections/PublishGuide.app.dotnet.md new file mode 100644 index 0000000000..b03c552e90 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/PublishGuide.app.dotnet.md @@ -0,0 +1,7 @@ +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- CLI: `winapp publish` — see [`winapp` CLI](https://github.com/microsoft/WinAppCli). + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). diff --git a/dev/Templates/Source/TemplateReadmeSections/PublishGuide.app.vsix.md b/dev/Templates/Source/TemplateReadmeSections/PublishGuide.app.vsix.md new file mode 100644 index 0000000000..1a61675ac4 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/PublishGuide.app.vsix.md @@ -0,0 +1,8 @@ +## Publish guide + +A redistributable MSIX requires a `.wapproj` alongside this app project (it owns `Package.appxmanifest`, signing, and bundle config). + +- *Add → New Project → Windows Application Packaging Project*, then *Add → Reference* this app project. +- Right-click `.wapproj` → *Publish → Create App Packages*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). diff --git a/dev/Templates/Source/TemplateReadmeSections/PublishGuide.wapproj.vsix.md b/dev/Templates/Source/TemplateReadmeSections/PublishGuide.wapproj.vsix.md new file mode 100644 index 0000000000..d2f81599be --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/PublishGuide.wapproj.vsix.md @@ -0,0 +1,7 @@ +## Publish guide + +This two-project shape **is** the redistributable-MSIX shape — the `.wapproj` already owns `Package.appxmanifest`, signing, and bundle config. + +- Right-click `.wapproj` → *Publish → Create App Packages*. + +See [Package and deploy a WinUI 3 desktop app](https://learn.microsoft.com/windows/apps/package-and-deploy/). diff --git a/dev/Templates/Source/TemplateReadmeSections/SecurityGuide.md b/dev/Templates/Source/TemplateReadmeSections/SecurityGuide.md new file mode 100644 index 0000000000..24cd6c3008 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/SecurityGuide.md @@ -0,0 +1,8 @@ +## Security guide + +External guides: + +- [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) — trim `Package.appxmanifest` +- [Credential Locker](https://learn.microsoft.com/windows/uwp/security/credential-locker) / [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview) — secrets storage +- [Create a certificate for package signing](https://learn.microsoft.com/windows/msix/package/create-certificate-package-signing) +- [.NET secure coding guidelines](https://learn.microsoft.com/dotnet/standard/security/secure-coding-guidelines) diff --git a/dev/Templates/Source/TemplateReadmeSections/TestingGuide.library.md b/dev/Templates/Source/TemplateReadmeSections/TestingGuide.library.md new file mode 100644 index 0000000000..ad58165bc0 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/TestingGuide.library.md @@ -0,0 +1,8 @@ +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyLibrary.Tests`, then `dotnet add reference ../MyLibrary/MyLibrary.csproj`. +- Tests run inside an MSIX, so dependency-property and `INotifyPropertyChanged` plumbing works in test cases. +- API-break detection: [Microsoft.DotNet.ApiCompat.Tool](https://www.nuget.org/packages/Microsoft.DotNet.ApiCompat.Tool). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). diff --git a/dev/Templates/Source/TemplateReadmeSections/TestingGuide.md b/dev/Templates/Source/TemplateReadmeSections/TestingGuide.md new file mode 100644 index 0000000000..db31f29797 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/TestingGuide.md @@ -0,0 +1,7 @@ +## Testing guide + +- Companion test template: `dotnet new winui-unittest -n MyApp.Tests` (or *Add → New Project → WinUI 3 Unit Test Project*). +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). +- UI automation: [WinAppDriver](https://github.com/microsoft/WinAppDriver). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro). diff --git a/dev/Templates/Source/TemplateReadmeSections/TestingGuide.unittest.md b/dev/Templates/Source/TemplateReadmeSections/TestingGuide.unittest.md new file mode 100644 index 0000000000..83c1b5bbd8 --- /dev/null +++ b/dev/Templates/Source/TemplateReadmeSections/TestingGuide.unittest.md @@ -0,0 +1,6 @@ +## Writing tests guide + +- Reference code under test: `dotnet add reference ..\MyApp\MyApp.csproj` (or `dotnet add package `). For internal types, add `[assembly: InternalsVisibleTo("MyApp.Tests")]`. +- Mocking: [Moq](https://github.com/devlooped/moq), [NSubstitute](https://nsubstitute.github.io/). + +See [Unit testing with MSTest](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-intro) for `[TestMethod]`, `[DataTestMethod]`, `[TestInitialize]`, etc. diff --git a/dev/Templates/Source/Validate-VSIXBuilds.ps1 b/dev/Templates/Source/Validate-VSIXBuilds.ps1 new file mode 100644 index 0000000000..bb96d1f857 --- /dev/null +++ b/dev/Templates/Source/Validate-VSIXBuilds.ps1 @@ -0,0 +1,68 @@ +$msbuild = "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" +$projects = @( + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/WinUI.Desktop.Cs.SingleProjectPackagedApp.csproj", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/WinUI.Desktop.Cs.NavigationApp.csproj", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/WinUI.Desktop.Cs.MvvmApp.csproj", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/WinUI.Desktop.Cs.TabViewApp.csproj", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/WinUI.Desktop.Cs.ClassLibrary.csproj", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/WinUI.Desktop.Cs.UnitTestApp.csproj", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/PackagedApp/WinUI.Desktop.Cs.PackagedApp.csproj" +) +$agents = @( + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/SingleProjectPackagedApp/AGENTS.md", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/NavigationApp/AGENTS.md", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/MvvmApp/AGENTS.md", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/TabViewApp/AGENTS.md", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/ClassLibrary/AGENTS.md", + "dev/Templates/Source/ProjectTemplates/Desktop/CSharp/UnitTestApp/AGENTS.md" +) + +$results = @() +$overallPass = $true +$firstFailure = "" + +foreach ($proj in $projects) { + Write-Host "Building $proj using Visual Studio MSBuild..." + $output = & $msbuild $proj /t:Build /p:Configuration=Release /v:minimal /nologo 2>&1 + $exitCode = $LASTEXITCODE + $vssdkMatch = $false + foreach($line in $output) { + if ($line -like "*VSSDK1016*") { + $vssdkMatch = $true + break + } + } + + $results += [PSCustomObject]@{ + Project = Split-Path $proj -Leaf + ExitCode = $exitCode + VSSDK1016 = $vssdkMatch + } + + if ($exitCode -ne 0 -and $overallPass) { + $overallPass = $false + $firstFailure = "Build failed for $(Split-Path $proj -Leaf) with exit code $exitCode" + } + if ($vssdkMatch -and $overallPass) { + $overallPass = $false + $firstFailure = "VSSDK1016 found in $(Split-Path $proj -Leaf)" + } +} + +foreach ($agentsFile in $agents) { + if (-not (Test-Path $agentsFile)) { + if ($overallPass) { + $overallPass = $false + $firstFailure = "AGENTS.md not found: $agentsFile" + } + Write-Host "AGENTS.md missing: $agentsFile" + } +} + +$results | Format-Table +if ($overallPass) { + Write-Host "OVERALL VERDICT: PASS" +} else { + Write-Host "OVERALL VERDICT: FAIL" + Write-Host "First Failure: $firstFailure" +} \ No newline at end of file diff --git a/dev/Templates/VSIX/templates/Desktop/CSharp/ClassLibrary/AGENTS.md b/dev/Templates/VSIX/templates/Desktop/CSharp/ClassLibrary/AGENTS.md new file mode 100644 index 0000000000..f91b4827a7 --- /dev/null +++ b/dev/Templates/VSIX/templates/Desktop/CSharp/ClassLibrary/AGENTS.md @@ -0,0 +1,43 @@ +# WinUI 3 class library + +A WinUI 3 class library — a reusable component (controls, helpers, +services, resources) that other WinUI 3 desktop apps can reference. + +A class library has **no app shell**: no `App.xaml`, no +`Package.appxmanifest`, no entry point. It's consumed by an app project, +which is what gives it identity at runtime. + +## Project layout + +| Path | Purpose | +| ----------------------- | ----------------------------------------------------------------------------- | +| `Class1.cs` | Starter type. Rename it or delete it as you add real types. | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +XAML controls, styles, and resource dictionaries can be added through the +Visual Studio **Add → New Item** dialog (templated control, user control, +resource dictionary, and friends). + +####Prerequisites.md#### + +####BuildAndRun.library.vsix.md#### + +####CommonNextSteps.library.vsix.md#### + +####AppArchitectureGuide.library.md#### + +####TestingGuide.library.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.vsix.md#### diff --git a/dev/Templates/VSIX/templates/Desktop/CSharp/MvvmApp/AGENTS.md b/dev/Templates/VSIX/templates/Desktop/CSharp/MvvmApp/AGENTS.md new file mode 100644 index 0000000000..8b28099d51 --- /dev/null +++ b/dev/Templates/VSIX/templates/Desktop/CSharp/MvvmApp/AGENTS.md @@ -0,0 +1,46 @@ +# WinUI 3 desktop MVVM app + +A WinUI 3 desktop app pre-wired with the +[CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) +source generators (`ObservableObject`, `[ObservableProperty]`, +`[RelayCommand]`), packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `Frame` that loads `MainPage`. | +| `MainPage.xaml`, `MainPage.xaml.cs` | First page, bound to `MainPageViewModel` via `{x:Bind}`. | +| `ViewModels/MainPageViewModel.cs` | Example view model deriving from `ObservableObject`, using `[ObservableProperty]` and `[RelayCommand]`. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +####Prerequisites.md#### + +####BuildAndRun.app.vsix.md#### + +####CommonNextSteps.app.vsix.md#### + +####PublishGuide.app.vsix.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.vsix.md#### diff --git a/dev/Templates/VSIX/templates/Desktop/CSharp/NavigationApp/AGENTS.md b/dev/Templates/VSIX/templates/Desktop/CSharp/NavigationApp/AGENTS.md new file mode 100644 index 0000000000..3706ca7ce0 --- /dev/null +++ b/dev/Templates/VSIX/templates/Desktop/CSharp/NavigationApp/AGENTS.md @@ -0,0 +1,45 @@ +# WinUI 3 desktop app with navigation + +A WinUI 3 desktop app pre-wired with `NavigationView` for top- or side-nav +patterns, packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar`, a `NavigationView`, and a `Frame` (`NavFrame`) that hosts pages. | +| `Pages/HomePage.xaml`, `.xaml.cs` | Default landing page navigated into `NavFrame`. | +| `Pages/AboutPage.xaml`, `.xaml.cs` | About page wired to a `NavigationViewItem`. | +| `Pages/SettingsPage.xaml`, `.xaml.cs` | Settings page wired to the `NavigationView` settings item. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +####Prerequisites.md#### + +####BuildAndRun.app.vsix.md#### + +####CommonNextSteps.app.vsix.md#### + +####PublishGuide.app.vsix.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.vsix.md#### diff --git a/dev/Templates/VSIX/templates/Desktop/CSharp/PackagedApp/AGENTS.md b/dev/Templates/VSIX/templates/Desktop/CSharp/PackagedApp/AGENTS.md new file mode 100644 index 0000000000..f27998ff42 --- /dev/null +++ b/dev/Templates/VSIX/templates/Desktop/CSharp/PackagedApp/AGENTS.md @@ -0,0 +1,57 @@ +# WinUI 3 desktop app (two-project packaged) + +A two-project WinUI 3 desktop app: a `.csproj` for code and a `.wapproj` +for MSIX packaging. Built on the Windows App SDK. + +> [!TIP] +> If you're starting a new app, prefer the single-project **WinUI 3 +> desktop app** template — it packages itself directly from the `.csproj`, +> no `.wapproj` required. Use this two-project shape only when you need +> the `.wapproj` indirection (for example, to package multiple processes +> together or to interop with existing `.wapproj`-based build flows). + +## Project layout + +``` +MySolution.sln +├── MyApp/ # The code project +│ ├── App.xaml, App.xaml.cs +│ ├── MainWindow.xaml, MainWindow.xaml.cs +│ ├── Properties/ +│ ├── app.manifest +│ └── MyApp.csproj +└── MyApp.Package/ # The packaging project + ├── Images/ # Tile, splash, store logos + ├── Package.appxmanifest # App identity and capabilities + └── MyApp.Package.wapproj +``` + +The `.wapproj` references the `.csproj` and owns the manifest, visual +assets, and MSIX output. The `.csproj` owns code, XAML, and target +framework. + +####Prerequisites.md#### + +####BuildAndRun.wapproj.vsix.md#### + +####CommonNextSteps.wapproj.vsix.md#### + +####PublishGuide.wapproj.vsix.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.vsix.md#### diff --git a/dev/Templates/VSIX/templates/Desktop/CSharp/SingleProjectPackagedApp/AGENTS.md b/dev/Templates/VSIX/templates/Desktop/CSharp/SingleProjectPackagedApp/AGENTS.md new file mode 100644 index 0000000000..a13f3c9240 --- /dev/null +++ b/dev/Templates/VSIX/templates/Desktop/CSharp/SingleProjectPackagedApp/AGENTS.md @@ -0,0 +1,42 @@ +# WinUI 3 desktop app + +A blank WinUI 3 desktop app packaged as MSIX, built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------- | --------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `Frame` (`RootFrame`) that displays pages. | +| `MainPage.xaml`, `MainPage.xaml.cs` | First page navigated to inside `RootFrame`. Page-level UI goes here. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +####Prerequisites.md#### + +####BuildAndRun.app.vsix.md#### + +####CommonNextSteps.app.vsix.md#### + +####PublishGuide.app.vsix.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.vsix.md#### diff --git a/dev/Templates/VSIX/templates/Desktop/CSharp/TabViewApp/AGENTS.md b/dev/Templates/VSIX/templates/Desktop/CSharp/TabViewApp/AGENTS.md new file mode 100644 index 0000000000..cd34181d5d --- /dev/null +++ b/dev/Templates/VSIX/templates/Desktop/CSharp/TabViewApp/AGENTS.md @@ -0,0 +1,44 @@ +# WinUI 3 desktop app with tabs + +A WinUI 3 desktop app pre-wired with `TabView` for multi-document or +multi-workspace layouts, packaged as MSIX and built on the Windows App SDK. + +## Project layout + +| Path | Purpose | +| --------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `App.xaml`, `App.xaml.cs` | Application entry point and lifetime. | +| `MainWindow.xaml`, `MainWindow.xaml.cs` | Top-level window. Hosts a `TitleBar` and a `TabView` whose tabs host `Frame`-based content. | +| `Pages/HomePage.xaml`, `.xaml.cs` | Default page content for the first tab. | +| `Pages/AboutPage.xaml`, `.xaml.cs` | Example secondary page; opened in another tab. | +| `Package.appxmanifest` | App identity, capabilities, visual assets, declarations. | +| `Assets/` | App icons, tile logos, splash screen, `AppIcon.ico`. | +| `Properties/` | `launchSettings.json` (Packaged / Unpackaged profiles) and per-arch publish profiles. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, and SDK version live here. | + +####Prerequisites.md#### + +####BuildAndRun.app.vsix.md#### + +####CommonNextSteps.app.vsix.md#### + +####PublishGuide.app.vsix.md#### + +####AppArchitectureGuide.md#### + +####TestingGuide.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.vsix.md#### diff --git a/dev/Templates/VSIX/templates/Desktop/CSharp/UnitTestApp/AGENTS.md b/dev/Templates/VSIX/templates/Desktop/CSharp/UnitTestApp/AGENTS.md new file mode 100644 index 0000000000..8d581e31fa --- /dev/null +++ b/dev/Templates/VSIX/templates/Desktop/CSharp/UnitTestApp/AGENTS.md @@ -0,0 +1,44 @@ +# WinUI 3 unit test project + +A WinUI 3 unit test project — an MSIX-packaged MSTest container that can +exercise WinUI 3 code in-process, with full access to +`Microsoft.UI.Xaml.*` types and a real `DispatcherQueue`. + +The test process is itself a WinUI 3 app (`UnitTestApp.xaml`) that hosts +the MSTest runner. Tests can construct controls, raise events, and await +dispatcher work the way real app code does. + +## Project layout + +| Path | Purpose | +| ------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `UnitTestApp.xaml`, `UnitTestApp.xaml.cs` | Test host application. Bootstraps the MSTest runner. | +| `UnitTestAppWindow.xaml`, `UnitTestAppWindow.xaml.cs` | Hidden window the host application uses for runner UI / dispatcher. | +| `UnitTests.cs` | Starter `[TestClass]` with example `[TestMethod]`s. Add more test classes alongside. | +| `Package.appxmanifest` | Test container identity. MSIX is required so WinUI 3 types can be exercised. | +| `Assets/` | Test container icons and visual assets. | +| `Properties/` | `launchSettings.json` and per-arch publish profiles for the test container. | +| `app.manifest` | Native side-by-side manifest (DPI awareness, supported OS versions). | +| `*.csproj` | Target framework, platforms, runtime identifier, MSTest references, and SDK version. | + +####Prerequisites.md#### + +####BuildAndRun.unittest.vsix.md#### + +####CommonNextSteps.unittest.vsix.md#### + +####TestingGuide.unittest.md#### + +####PerformanceGuide.md#### + +####AccessibilityGuide.md#### + +####GlobalizationGuide.md#### + +####SecurityGuide.md#### + +####DocumentationGuide.md#### + +--- + +####FrameworkFooter.vsix.md#### diff --git a/dev/Templates/how-to-create-a-new-csharp-template.md b/dev/Templates/how-to-create-a-new-csharp-template.md index 144a1190f3..65f5577693 100644 --- a/dev/Templates/how-to-create-a-new-csharp-template.md +++ b/dev/Templates/how-to-create-a-new-csharp-template.md @@ -47,6 +47,7 @@ the non-reserved name in Source. ``` dev/Templates/Dotnet/templates// + AGENTS.md (optional outline; see step 5) .template.config/ template.json (required) dotnetcli.host.json (CLI parameter aliases) @@ -90,7 +91,68 @@ shape: | `DotnetConfigDir` | Absolute path to `Dotnet/templates//`. | When ships to dotnet-new | | `RenameManifestFrom` | Source-side manifest filename, typically `Package-managed.appxmanifest`. Packed as `Package.appxmanifest`. | Packaged WinUI app templates only | -### 5. Local build for tests +### 5. (Optional) Per-template AGENTS.md + +If the template should ship an `AGENTS.md` that users (and AI agents) +see in their new project root, drop an `AGENTS.md` **outline** in the +channel-specific location: + +| Channel | Outline location | +| ---------- | ------------------------------------------------------------------------- | +| dotnet-new | `Dotnet/templates//AGENTS.md` (next to `.template.config/`) | +| VSIX | `VSIX/templates/Desktop/CSharp//AGENTS.md` | + +An outline mixes inline prose (title, intro, project-layout diagram) +with `####FileName.md####` placeholders that name section files in +[`Source/TemplateReadmeSections/`](Source/TemplateReadmeSections) **verbatim**: + +```markdown +# WinUI 3 desktop MVVM app + +A WinUI 3 desktop app pre-wired with the MVVM pattern... + +## Project layout +... + +####Prerequisites.md#### +####BuildAndRun.app.vsix.md#### +####CommonNextSteps.app.vsix.md#### +####PublishGuide.app.vsix.md#### +``` + +Reusable section files live under +[`Source/TemplateReadmeSections/`](Source/TemplateReadmeSections). Their +filenames bake the channel/shape suffix (`.app.vsix.md`, +`.library.dotnet.md`, `.wapproj.vsix.md`, …) so the outline can +pinpoint the exact file — no inference, no fallback chain. + +At build / pack time the outline is merged into the final `AGENTS.md` +that ships in the produced template: + +- **dotnet-new**: merged inside `ExpandProjectTemplatePackItems` and + packed as `content//AGENTS.md`. +- **VSIX**: merged by `_GenerateMergedReadme` + (in [`Source/Directory.Build.targets`](Source/Directory.Build.targets)) + directly next to the `.vstemplate` (i.e. into + `$(MSBuildProjectDirectory)\AGENTS.md`) so the VS SDK packs it + into the project-template `.zip`. The generated file is `.gitignore`d + and removed by `Clean`. + +For VSIX templates, the `.vstemplate` must also list the file so VS +copies it into the user's new project: + +```xml +AGENTS.md +``` + +`ReplaceParameters="false"` is intentional — the file is already in +its final shipping form at build time; VS must not re-scan it for +`$xxx$` substitution (which would corrupt example shell variables or +text that happens to contain `$...$` strings). See +[Per-template AGENTS.md assembly](#per-template-agentsmd-assembly) below +for the full pipeline. + +### 6. Local build for tests 1. dotnet new template: @@ -173,14 +235,19 @@ We replaced it with an **inline C# MSBuild task** — `ExpandProjectTemplatePackItems` in [`WinAppSdk.CSharp.DotnetNewTemplates.csproj`](Dotnet/WinAppSdk.CSharp.DotnetNewTemplates.csproj). It takes `@(ProjectTemplate)` (or `@(ItemTemplate)`, etc.) and per -template performs the same four-step packing recipe: +template performs the same five-step packing recipe: 1. Pack everything under `SourceDir`, minus `bin/`, `obj/`, and the per-template sidecars (`.csproj` / `.ico` / `.png` / `.vstemplate`). 2. If `RenameManifestFrom` is set, re-pack that manifest under the reserved name `Package.appxmanifest`. 3. Pack everything under `DotnetConfigDir/.template.config/`. -4. Pack a copy of the shared `.gitignore` (project templates only). +4. If `DotnetConfigDir` contains an `AGENTS.md` outline, merge it + (substituting `####FileName.md####` placeholders with files from + [`Source/TemplateReadmeSections/`](Source/TemplateReadmeSections)) and pack + the result as `content//AGENTS.md`. See + [Per-template AGENTS.md assembly](#per-template-agentsmd-assembly) below. +5. Pack a copy of the shared `.gitignore` (project templates only). ### Why a C# task and not a pure-MSBuild `` with batching @@ -225,6 +292,85 @@ The convention is therefore: The `RenameManifestFrom` metadata is what tells the inline task to perform that rename. +### Per-template AGENTS.md assembly + +Per-template `AGENTS.md` files are not authored as monolithic files. Each +template ships a per-channel **outline** (short, template-specific +prose) that embeds `####FileName.md####` placeholders pointing at +shared **section files** in +[`Source/TemplateReadmeSections/`](Source/TemplateReadmeSections). At +build / pack time an MSBuild task expands those placeholders into the +final `AGENTS.md` that the produced template ships. + +> **Design intent.** `Source/` is meant to be the **shared canonical +> content area** consumed by both the dotnet-new and the VSIX channels. +> The sections folder lives there for that reason. Today `Source/` also +> still contains VSIX-only sidecars (`.vstemplate`, `.ico`, `.png`, the +> twin `.csproj`) for legacy reasons; relocating those to `VSIX/` so +> `Source/` is purely shared is a known future cleanup. + +#### Inputs + +| Kind | Path | Purpose | +| ---------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| Outline (dotnet) | `Dotnet/templates//AGENTS.md` | Per-template prose; merged when packing the dotnet-new NuGet. | +| Outline (VSIX) | `VSIX/templates/Desktop/CSharp//AGENTS.md` | Per-template prose; merged when building the VSIX twin csproj under `Source/`. | +| Section files | [`Source/TemplateReadmeSections/*.md`](Source/TemplateReadmeSections) | Reusable, shared prose consumed by both channels. Filename bakes the channel/shape suffix (`.app.vsix.md`, `.library.dotnet.md`, `.wapproj.vsix.md`, …). | + +#### Placeholder syntax + +Outlines reference sections by **literal filename**: + +```text +####Prerequisites.md#### +####BuildAndRun.app.vsix.md#### +####CommonNextSteps.library.dotnet.md#### +``` + +There is intentionally **no** shape/channel inference and **no** +fallback chain — the placeholder *is* the filename. A reader of any +outline can pinpoint the exact source of every embedded paragraph +without consulting resolver code. + +#### Merge tasks + +| Channel | Task | Where it lives | Output | +| ---------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| dotnet-new | `ExpandProjectTemplatePackItems` (step 4 of its packing recipe) | [`Dotnet/WinAppSdk.CSharp.DotnetNewTemplates.csproj`](Dotnet/WinAppSdk.CSharp.DotnetNewTemplates.csproj) | Merged file written under `$(IntermediateOutputPath)merged-readmes//AGENTS.md` and packed as `content//AGENTS.md`. | +| VSIX | `GenerateMergedReadme` (invoked by `_GenerateMergedReadme` target) | [`Source/Directory.Build.targets`](Source/Directory.Build.targets) (auto-imported by `Microsoft.Common.targets` for every Source twin csproj) | Merged file written to `$(MSBuildProjectDirectory)\AGENTS.md` (next to the `.vstemplate`, `.gitignore`d) so the VS SDK's `CreateProjectTemplateZipFile` task picks it up via the `.vstemplate`'s `AGENTS.md` reference. | + +Both tasks are deliberately a **single** `Regex.Replace` pass over the +outline: read outline → for each `####File.md####` match, substitute +`File.ReadAllText(Source/TemplateReadmeSections/File.md).TrimEnd()` → +collapse runs of 3+ newlines → fail the build on any missing file or +leftover marker. There are no helpers and no conditional branches +around content massaging. + +#### VSIX wiring + +For VSIX templates the merged `AGENTS.md` must also be advertised in +the `.vstemplate` so VS copies it into the user's new project: + +```xml +AGENTS.md +``` + +`ReplaceParameters="false"` is intentional: the file is already in +its final shipping form, and VS must not rescan it for `$xxx$` +substitution (which could corrupt example shell variables, code +fragments, or text that happens to contain `$...$` strings). + +#### Build-time guarantees + +Both tasks fail the build if: + +- An outline references a section file that does not exist. +- A `####...####` marker survives substitution (i.e. malformed + placeholder). +- The merged content cannot be written. + +A typo in an outline therefore cannot silently ship to users. + ### VSIX consumption The VSIX csproj converts the same manifest into `` @@ -275,13 +421,21 @@ dev/Templates/ │ ├── WinAppSdk.CSharp.DotnetNewTemplates.csproj │ ├── Directory.Build.props │ └── templates// +│ ├── AGENTS.md ← optional outline (dotnet channel) │ └── .template.config/ │ ├── template.json │ ├── dotnetcli.host.json │ ├── ide.host.json │ └── icon.png -├── Source/ ← actual template content (C# and C++) -│ ├── ProjectTemplates/Desktop/CSharp// +├── Source/ ← shared canonical content consumed by both channels +│ ├── Directory.Build.targets ← merges per-template READMEs for VSIX twin csprojs +│ ├── TemplateReadmeSections/ ← reusable README section files (channel/shape suffixes baked into the filename) +│ │ ├── Prerequisites.md +│ │ ├── BuildAndRun.app.dotnet.md +│ │ ├── BuildAndRun.app.vsix.md +│ │ ├── ... (30 files total — see folder for full list) +│ │ └── FrameworkFooter.vsix.md +│ ├── ProjectTemplates/Desktop/CSharp// ← currently also holds VSIX-only sidecars (see note below) │ │ ├── .csproj │ │ ├── .{ico,png,vstemplate} │ │ ├── Package-managed.appxmanifest (if packaged) @@ -293,9 +447,18 @@ dev/Templates/ ├── WindowsAppSDK.Extension.sln ├── Extension/Cs/Dev17/WindowsAppSDK.Cs.Extension.Dev17.csproj ← C# VSIX (consumes templates.props) ├── Extension/Cpp/Dev17/WindowsAppSDK.Cpp.Extension.Dev17.csproj ← C++ VSIX (does NOT import templates.props) + ├── templates/Desktop/CSharp// + │ └── AGENTS.md ← optional outline (VSIX channel) └── Directory.Build.props ``` +> **Note on `Source/`.** The intent is that `Source/` holds **only** +> content that is shared by both the dotnet-new and the VSIX channels. +> Today the per-template VSIX sidecars (`.vstemplate`, `.ico`, `.png`, +> the twin `.csproj`) still live alongside the source files for legacy +> reasons. Moving those into `VSIX/` so `Source/` is purely shared is a +> known future cleanup. + --- ## FAQ @@ -322,3 +485,20 @@ For C++ templates, add the template content under and a corresponding `` to the C++ vsixmanifest. There is no dotnet-new pack for C++/WinRT templates yet. + +--- + +## Validating VSIX builds + +Before submitting changes, validate that all VSIX templates build successfully and include the required `AGENTS.md` files. Use the provided PowerShell script: + +``` +pwsh dev/Templates/Source/Validate-VSIXBuilds.ps1 +``` + +This script: +- Builds all VSIX templates in `Release` configuration. +- Checks for `VSSDK1016` errors during packaging. +- Verifies that `AGENTS.md` files are generated for all project templates. + +If the script reports any failures, resolve them before submitting your changes.