Track WinUI workshop failures across skills, templates, analyzers, docs, and CLI

Summary

A WinUI 3 build exercise exposed a set of repeatable failures across project creation, API selection, visual iteration, packaging, and launch. This issue tracks the cases in one place until each has a minimal verified reproduction and is either fixed here or transferred to the correct owning repository.

The guiding principle is to prefer enforceable fixes in this order:

1. Product or template default
2. Build guard or analyzer
3. Grounded API documentation or runnable sample
4. Skill instruction only when the behavior cannot be enforced elsewhere

The source exercise contained internal material, so this issue intentionally includes only sanitized technical reproductions and no participant names, internal links, or confidential quotations.

Checklist

• 1. Remove the project-local BuildAndRun.ps1 assumption
• 2. Guard CommunityToolkit partial-property generation by language version
• 3. Detect WPF-style Storyboard.SetSpeedRatio
• 4. Provide a reliable immersive dark-page theming pattern
• 5. Guard against Storyboard/local-value ownership conflicts
• 6. Cover a second property affected by the same animation-ownership defect
• 7. Require runtime verification before reporting UI changes complete
• 8. Reproduce and escalate the same-page connected-animation crash
• 9. Document the supported lifecycle for recurring connected animations
• 10. Define an offline/pre-staged self-contained packaging workflow
• 11. Remove unsafe trimming defaults from WinUI guidance
• 12. Preserve regression coverage for self-contained executable inference
• 13. Define and automate the development-certificate trust workflow
• 14. Guard incompatible BuildTools/WinAppSDK deployment combinations
• 15. Add grounded in-box Composition examples
• 16. Recover the missing non-WinUI-control reproduction before assigning work
• 17. Preserve regression coverage for automatic template-pack installation
• 18. Improve or document triage for misleading XAML compiler null references
• 19. Require completion of agent-created TODOs
• 20. Validate the complete packaging workflow and deployment matrix
• 21. Investigate and surface early-startup failures
• 22. Verify pristine templates across supported environments

1. Project-local BuildAndRun.ps1 assumption

Reproduction

1. Install the WinUI plugin.
2. Scaffold a project with winapp new --template winui-mvvm --name Repro --use-defaults.
3. Change into Repro.
4. Follow guidance that invokes ./BuildAndRun.ps1.

Actual: the generated project does not contain the plugin-owned script.

Expected: normal development uses winapp run . --debug-output without requiring a copied helper.

Preferred fix: finish moving required helper behavior into WinApp CLI, update all agent/skill references, and remove the script in the next release. Do not modify official project templates merely to carry a plugin helper.

2. Partial properties under an unsupported language version

Reproduction

1. Use .NET SDK 9 with a project compiling as C# 12.
2. Generate a CommunityToolkit property using:

[ObservableProperty]
public partial string Name { get; set; }

3. Build the project.

Actual: compilation can fail with partial-property/language-version errors such as CS9248 or CS8050.

Expected: generated source is compatible with the selected SDK and language version.

Preferred fix: project templates should select the appropriate syntax from the effective language version. Analyzer/code-fix guidance must offer the field-backed form when partial properties are unavailable.

3. WPF-style Storyboard.SetSpeedRatio

Reproduction

var storyboard = new Storyboard();
Storyboard.SetSpeedRatio(storyboard, 2.0);

Build in a WinUI 3 project.

Actual: the WPF-shaped API is unavailable and compilation fails.

Expected: use the WinUI/Timeline property:

storyboard.SpeedRatio = 2.0;

Preferred fix: add an analyzer diagnostic and code fix, backed by a small grounded API example.

4. Immersive dark page under a light system theme

Reproduction

1. Run Windows with the light app theme.
2. Create a page with a custom dark background.
3. Add standard controls such as SelectorBar without establishing a theme boundary.
4. Launch and capture a screenshot.

Actual: system-themed labels and controls can have insufficient contrast against the custom dark surface.

Expected: an immersive dark subtree establishes RequestedTheme="Dark" at the correct boundary and remains accessible.

Preferred fix: provide a reusable template or grounded design pattern rather than relying on a prose reminder.

5. Storyboard and local value both own one property

Reproduction

1. Animate an element's Opacity with a repeating Storyboard.
2. Handle a Slider change by assigning a local value to the same Opacity property.
3. Move the Slider while the animation is active.

Actual: the animation clock retains effective ownership, so the Slider appears to have little or no effect.

Expected: one owner per animated property. Stop/remove the animation before setting the base value, or map the user control to a separate visual property.

Preferred fix: add a concise grounded API pattern. Prototype an analyzer only if the XAML/code-behind ownership collision can be detected with acceptably low false positives.

6. Second animation-ownership collision

Use the reproduction from item 5 with a second Slider and animated property—for example a warmth control writing an opacity that another Storyboard owns.

Expected: the same single-owner rule applies consistently.

Preferred fix: one implementation should close items 5 and 6; retain two regression scenarios to demonstrate that the guard is property-agnostic.

7. UI change reported complete without runtime verification

Reproduction

1. Ask the agent to change both an app icon and an in-window navigation/menu position.
2. Introduce or retain a state where only part of the request is implemented.
3. Allow the agent to stop after editing or building without relaunching.

Actual: the agent can report completion while the old icon or layout remains visible.

Expected: the completion path launches the app, runs winapp ui inspect, captures a screenshot, and performs one bounded correction pass before reporting success.

Preferred fix: update the main agent process. This is an orchestration concern rather than domain knowledge that belongs in every skill.

8. Same-page ConnectedAnimationService crash

Reproduction to verify

1. Place source and destination elements on the same page.
2. Prepare a connected animation from the source.
3. Keep both elements in the page's layout and start the animation on the destination.
4. Repeat the transition.

Observed failure: a native access violation in Microsoft.UI.Xaml.dll was reported in the source exercise.

Expected: supported behavior or a diagnosable managed failure—never a native process crash.

Preferred fix: create a standalone reproduction against current Windows App SDK versions. If confirmed, file it upstream and link the issue here. Add a safe sample only after supported behavior is established.

9. Timer-driven connected animation without a view transition

Reproduction to verify

1. Create a connected animation.
2. Trigger it repeatedly from a DispatcherTimer without navigation or a user-driven view transition.

Actual: the connected visual may not render reliably.

Expected: documentation and samples clearly define the required lifecycle and direct autonomous effects to Storyboard or Composition animations.

Preferred fix: grounded API documentation/sample; escalate upstream if platform behavior contradicts the documented contract.

10. Self-contained packaging without NuGet connectivity

Reproduction

1. Use a clean machine or environment where NuGet package download is unavailable.
2. Run winapp package <build-output> --self-contained without the necessary runtime already cached.

Actual: packaging fails while attempting to acquire Windows App SDK runtime assets.

Expected: either consume a pre-staged self-contained publish folder or fail with an actionable command sequence explaining how to stage dependencies and retry.

Preferred fix: WinApp CLI behavior and documentation. This issue should track transfer to microsoft/winappCli if no skill-only work remains.

11. Unsafe default trimming guidance

Reproduction

1. Publish a WinUI 3 app with:

<PublishTrimmed>true</PublishTrimmed>
<TrimMode>full</TrimMode>

2. Include WinRT activation, reflection, serialization, resources, or framework features without established trim annotations.
3. Review warnings and test the packaged app.

Actual: the build can emit WinRT trimming warnings and runtime safety is not established.

Expected: WinUI guidance defaults to PublishTrimmed=false. Trimming is an explicit optimization attempted only with warning-free builds and representative runtime tests.

Preferred fix: correct the source-generation/AOT reference, use conservative template defaults, and add build guards where supported.

12. Self-contained executable inference

Reproduction/regression test

1. Produce a self-contained folder containing the app executable plus runtime helpers such as createdump.exe, apphost.exe, RestartAgent.exe, or DeploymentAgent.exe.
2. Run winapp package <folder> without --executable.

Previous failure: runtime helpers made entry-point inference ambiguous.

Current expected behavior: known runtime helpers are ignored and the single application executable is selected. Genuine ambiguity lists candidates and requests --executable.

Status: fixed in WinApp CLI. Keep the regression test and periodically validate it using a real self-contained publish layout.

13. Development-certificate trust

Reproduction

1. Generate a self-signed development certificate.
2. Trust it only in a current-user certificate store.
3. Sign an MSIX and run Add-AppxPackage on a clean machine.

Actual: installation can fail with 0x800B0109 (CERT_E_UNTRUSTEDROOT).

Expected: the supported development workflow establishes the required machine trust explicitly and exports only the public .cer for distribution.

Preferred fix: decide and document which machine stores winapp cert install owns, automate that supported configuration, use winapp cert generate --export-cer, and state prominently that the private .pfx must never be distributed.

14. Incompatible BuildTools override

Reproduction to verify

1. Use a WinUI 3 project targeting .NET 9 and Windows App SDK 2.4.
2. Explicitly override Microsoft.Windows.SDK.BuildTools to an incompatible version such as 10.0.28000.
3. Publish/package and launch.

Observed failure: startup failed before a window appeared with TypeLoadException/MissingMethodException in generated C#/WinRT startup code.

Expected: dependency resolution selects a compatible BuildTools version, or the build emits a clear incompatibility diagnostic.

Preferred fix: dependency/build guard first. Guidance should discourage manual BuildTools overrides and explain clearing stale publish/staging output after dependency changes.

15. Win2D selected when in-box Composition is sufficient

Reproduction

1. Ask for an animated radial-gradient effect in a WinUI 3 app.
2. Run in an environment where external NuGet restore is unavailable.
3. Observe an implementation that adds Win2D despite the effect being possible with Microsoft.UI.Composition.

Actual: an unnecessary package dependency blocks restore and increases deployment complexity.

Expected: grounded lookup ranks an in-box Composition implementation first, including CompositionRadialGradientBrush, keyframe animation, and playback-rate examples.

Preferred fix: add Composition scenarios to the grounded sample corpus and improve find-ui ranking. Keep only a short routing rule in the skill.

16. Non-WinUI-control instruction lacks evidence

The source record says the prompt requested only WinUI 3 controls, but it does not record what the agent generated, which control was wrong, or what failure resulted.

Next step: obtain the original prompt/output or a concrete control name before assigning ownership. Do not add speculative skill text.

17. WinUI template assumed to ship with .NET

Reproduction/regression test

1. Start with a clean .NET SDK installation and no WinUI template pack.
2. Run winapp new --template winui --name Repro --use-defaults.

Previous failure: direct dotnet new winui usage failed because the template was not installed.

Current expected behavior: winapp new discovers and installs the official template pack, then scaffolds the project.

Status: fixed. Retain clean-environment tests for installation, version selection, and supported template short names.

18. Code-behind syntax error reported as XAML compiler failure

Reproduction to verify

1. Add an extra closing brace to MainPage.xaml.cs.
2. Build the associated WinUI project.

Observed failure: the XAML compilation pipeline emitted a null-reference-style failure rather than a useful C# syntax diagnostic.

Expected: the compiler identifies the source file and syntax error. Until fixed upstream, troubleshooting should check code-behind syntax before editing valid XAML.

Preferred fix: minimal upstream compiler reproduction plus a narrowly targeted troubleshooting entry.

19. Agent-created TODO left incomplete

Reproduction

1. Give the agent a multi-part app-generation request.
2. Let it introduce a TODO placeholder for part of the requested behavior.
3. Allow it to report completion without searching for unresolved placeholders.

Actual: requested functionality remains incomplete until the user asks again.

Expected: before completion, search changed files for agent-created TODOs/placeholders, finish them, then build, launch, inspect, and screenshot.

Preferred fix: main-agent completion gate. One process change should close both items 7 and 19.

Proposed ownership breakdown

Templates and defaults

• Item 2: language-version-compatible CommunityToolkit property syntax
• Item 4: reusable immersive-theme pattern
• Item 11: conservative trimming defaults

Build guards and analyzers

• Item 3: WPF Storyboard.SetSpeedRatio
• Items 5–6: animation/local-value ownership, if detectable reliably
• Item 14: incompatible dependency combinations

Grounded API documentation and samples

• Items 3 and 9: animation semantics
• Item 15: in-box Composition patterns
• Item 18: temporary troubleshooting guidance

Agent process

• Items 7 and 19: bounded runtime verification and completion discipline

WinApp CLI

• Item 1: remove helper dependency
• Item 10: offline/pre-staged self-contained packaging
• Item 13: development certificate trust

Upstream Windows App SDK / WinUI

• Item 8: native connected-animation crash
• Item 18: misleading XAML compiler failure

Needs evidence

• Item 16

Cross-cutting category coverage

• Remove BuildAndRun.ps1: tracked by item 1.
• Bounded visual iteration loop: tracked by items 7 and 19.
• Packaging guidance and testing: individual defects are tracked by items 10–14; the end-to-end validation matrix is tracked by item 20.
• Early-startup diagnostics: tracked by item 21, with related symptoms in items 13, 14, and 18.
• Ground iterative fixes: covered by the individual cases above.
• Verify pristine templates: template installation is covered by item 17; the broader clean-environment matrix is tracked by item 22.

20. Complete packaging workflow and deployment matrix

Scenarios to validate

• Packaged and unpackaged applications
• x64 and ARM64
• .NET framework-dependent and .NET self-contained deployment
• Windows App SDK framework-dependent and self-contained deployment
• Native AOT where supported
• Trimming disabled, and trimming explicitly enabled with warnings treated as actionable
• Development signing, public .cer distribution, certificate trust, installation, upgrade, and removal
• Automatic and explicit executable selection
• Online, cached, and disconnected dependency acquisition
• Installation and first launch on a clean machine

Expected: every documented configuration has one canonical command sequence, automated coverage where practical, and a clean-machine launch result. The guidance must distinguish .NET self-containment from Windows App SDK self-containment and must never imply that a private .pfx should be distributed.

Preferred fix: build the matrix as executable sample tests first, then update the packaging skill from those verified workflows. Track WinApp CLI defects in microsoft/winappCli and link them here rather than compensating with increasingly complex prose.

21. Early-startup diagnostics

Failure classes to reproduce

1. Activation failure before a process is created
2. Process starts and exits before creating a window
3. Package identity or registration mismatch
4. Missing or incompatible Windows App Runtime
5. Certificate trust or publisher mismatch
6. Architecture mismatch
7. Generated C#/WinRT startup failure
8. Failure visible only through AppModel, AppX deployment, or Application Event Log entries

Expected: winapp run --debug-output reports a specific activation or startup diagnosis whenever Windows exposes one. Structured output should include the failing phase, HRESULT/exception, package identity, application ID, PID when available, and an actionable next step.

Investigation requirements

• Capture a minimal project and command for each failure class.
• Determine which diagnostics are already available through process/debug APIs and which require Event Log correlation.
• Correlate Event Log records narrowly by launch time, package family/application ID, and PID where available; never surface unrelated historical events.
• Preserve equivalent diagnostics under --json.
• Transfer required CLI work to microsoft/winappCli and link it here.

22. Pristine-template verification

Matrix to reproduce

1. Start from a clean machine or isolated SDK/template cache.
2. Test each supported official WinUI application template and template version.
3. Cover every supported .NET SDK band and effective language version.
4. Cover x64 and ARM64 configuration mapping.
5. Run winapp new, restore, build, register, and launch without editing generated source.
6. Record the selected template-pack version, target framework, language version, Windows App SDK version, BuildTools version, architecture, and complete failure output.

Expected: every supported pristine template builds and launches, or fails immediately with a precise compatibility message before the user edits generated code.

Preferred fix: put compatibility selection and validation in templates, template CI, and WinApp CLI. Consider a winapp new --verify option only if the normal scaffold/run workflow cannot provide the same deterministic check. Keep skill guidance limited to invoking the verified path.

Start by splitting the 22-item checklist and identifying the owning area for each case: WinApp CLI commands, project templates, analyzers, agent process, documentation, or samples. Run the explicitly listed reproductions, preserving regression coverage for items 12 and 17. Done means each item has a verified minimal reproduction and is fixed here or transferred with a linked upstream issue.