microsoft / microsoft/winappCli
[Feature]: winapp run --watch: WinUI C#/XAML hot reload
@nmetulev is already working on this.
Since Jul 20, 2026.
- Dominant language
- C#
- Stars
- 1.3k
- Forks
- 80
- Avg merge
- 3d 6h
- Merged PRs (30d)
- 51
Description
Depends on: project-mode run support (#633), analyzer support (#634)
Summary
Add winapp run --watch so WinUI developers can keep an app running and see supported C# and XAML changes apply without a full manual rebuild/relaunch loop.
This is the inner-loop extension of project-mode run support: winapp run already builds and launches a WinUI project, and analyzer support adds diagnostics feedback. This proposal makes that loop iterative, so source edits become live app updates instead of repeated command reruns.
Problem
Today the CLI can build and run WinUI apps, but every meaningful source change still forces a manual rerun. That is too slow for the WinUI authoring loop and too noisy for agents that need to make small, repeated edits.
Visual Studio already has hot reload semantics for supported edits; the CLI path needs a comparable, editor-agnostic workflow that works from winapp.
Goals
- Support
winapp run --watchfor WinUI project-mode apps - Apply supported C# and XAML edits without restarting the app when possible
- Keep the running app and debugger connection alive across supported edits
- Give clear feedback when a change cannot be hot reloaded and a restart is needed
- Set up the future shared design-time engine path
Non-goals
- Building the live visual tree or property editor (tracked separately under design-time tooling)
- Adding support for other UI authoring models such as C# markup yet. That can be a follow-up once the WinUI and XAML path is proven.
- Turning
--watchinto a generic framework-agnostic watch mode - Replacing
dotnet watchfor every .NET project type
Proposed behavior
Watch loop
winapp run --watch <project>builds and launches the app, then watches the project inputs that matter for the inner loop.- On file changes,
winappshould attempt the fastest supported update path first:- C# changes -> hot reload if the edit is supported
- XAML changes -> XAML hot reload / UI refresh if the edit is supported
- If the change is not hot-reloadable,
winappshould clearly report that a restart or rebuild is required.
Scope
- Initial support is WinUI
.csprojproject mode. - The CLI should work with the project-mode build-and-launch pipeline rather than introducing a separate execution model.
- The watch loop should preserve the existing run-mode semantics for packaging, runtime install, and analyzer diagnostics.
Change handling
- C# edits should use the .NET hot reload path where available.
- XAML edits should use the WinUI hot reload path where available.
- If a change affects a supported but restart-sensitive surface,
winappshould restart in a controlled way instead of leaving the user in a broken state.
Key implementation constraints
- Prefer existing .NET / WinUI hot reload plumbing over a custom reinvention
- Keep the watch loop compatible with the analyzer and build behavior from the analyzer support
- Avoid regressing the non-watch
winapp runpath - Make the restart / hot-reload boundary explicit so agents can reason about it
Migration path
winapp run --watchbecomes the canonical watch workflow for WinUI source edits.- The same watch orchestration can later be backed by the shared design-time engine proposal.
- Other surfaces (VS Code extension, Visual Studio extension, agents) can then reuse the same live-update machinery instead of each owning their own watcher.
Success criteria
- A developer can run
winapp run --watchand edit C# or XAML without manually rerunning the command for common changes - Supported edits update the live app quickly and predictably
- Unsupported edits produce a clear restart/rebuild message
- The behavior works cleanly with the project-mode run and analyzer pipelines
Risks / watchouts
- Some XAML edits may still require restart depending on framework support
- Watch mode can easily become flaky if it tries to over-apply changes
- Packaged app scenarios may be more constrained than unpackaged ones
- If the watch loop and future design-time engine diverge, we risk duplicating logic
Why this matters
This is the step that turns winapp run from a build-and-launch command into a true WinUI inner-loop command: edit, refresh, repeat.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.