Skip to content

winapp run: fix packaged C++ Debug apps failing on the debug CRT path - #1030

Merged
Zach Teutsch (zateutsch) merged 11 commits into
mainfrom
nmetulev-cpp-vcxproj-run-support
Oct 8, 2026
Merged

Zach Teutsch (zateutsch) merged 11 commits into
mainfrom
nmetulev-cpp-vcxproj-run-support

Conversation

@nmetulev

@nmetulev Nikola Metulev (nmetulev) commented Oct 8, 2026 •

Copy link
Copy Markdown
Member

Description

I tested winapp run (main at 1662e76) on real open-source and Microsoft-sample C++ WinUI 3 apps. This PR fixes the problems that were on our side:

  1. Packaged C++ Debug apps fail after a successful build. MSBuild writes item paths in *.build.appxrecipe escaped, so the debug CRT appears as C:\Program Files %28x86%29\...\ucrtbased.dll. winapp looked for that literal path and refused to stage the layout. This hit Microsoft's PhotoEditor and Windowing C++ samples on Windows App SDK 1.5, 1.8 and 2.x. winapp now unescapes recipe source paths.
  2. Missing Windows SDK: wrong winget suggestion. For MSB8036 we always suggested Microsoft.WindowsSDK.10.0.26100, even when the project needs 10.0.22621. The hint now names the version from the MSBuild error.
  3. The ambiguity error hid the C++ app. When a solution or folder has several C# apps, the list of --project choices left out C++ app projects, even though --project <cpp app> works. They are now listed.
  4. Apps that require administrator rights. An exe whose manifest sets requireAdministrator failed with Windows' raw "The requested operation requires elevation". winapp now says what's going on.
  5. An architecture this machine can't run is refused before building. -p Platform=ARM64 (or --arch arm64) on an x64 PC built for minutes, then failed with a misleading Windows App Runtime error. It now fails right away. The suggested fix changes whichever option chose the architecture (-r, --arch or -p Platform). --no-launch and remote execution targets still build.
  6. vcpkg projects without MSBuild integration. A build that can't find headers, in a project with a vcpkg.json and no vcpkg MSBuild integration, now suggests vcpkg integrate install. "No integration" means MSBuild's evaluation of _ZVcpkgRoot is empty; only vcpkg.targets defines that property. A project that imports vcpkg itself gets no hint.

Usage Example

All output below is observed from the projects named.

PhotoEditor (microsoft/WindowsAppSDK-Samples, Samples\PhotoEditor\cpp-winui): winapp run . --detach --json

Before:

"Error": "The build did not produce 1 file(s) the recipe '...\x64\Debug\PhotoEditor\PhotoEditor.build.appxrecipe' lists: ucrtbased.dll (from 'C:\Program Files %28x86%29\Microsoft SDKs\Windows Kits\10\ExtensionSDKs\Microsoft.UniversalCRT.Debug\10.0.26100.0\Redist\Debug\x64\ucrtbased.dll'). Rebuild the project and try again."

After:

{
  "AUMID": "wrt-ms-photoeditor-test_s9y1p3hwd5qda!App",
  "ProcessId": 38584
}

WinUIEdit (BreeceW/WinUIEdit): winapp run WinUIEditor.sln --project CppDemoWinUI3 --detach --json

Before: ... winget install Microsoft.WindowsSDK.10.0.26100 ...
After:

Build failed for CppDemoWinUI3.vcxproj. The Windows SDK 10.0.22621 this project targets is not installed (MSB8036). Install it with the Visual Studio Installer or winget (e.g. winget install Microsoft.WindowsSDK.10.0.22621), or build against an installed one with -p:WindowsTargetPlatformVersion=<version>.

WinUIEdit: winapp run .

Before: 'WinUIEditor.sln' contains multiple runnable app projects (CsDemoWinUI3.csproj, WinFormsIslandsDemo.csproj, WpfIslandsDemo.csproj). ...
After: 'WinUIEditor.sln' contains multiple runnable app projects (CppDemoUwp.vcxproj, CppDemoWinUI3.vcxproj, CppIslandsDemo.vcxproj, CsDemoWinUI3.csproj, WinFormsIslandsDemo.csproj, WpfIslandsDemo.csproj). Specify which project to run with --project <name>.

StarlightGUI (OpenStarlight/StarlightGUI, Debug|x64 sets RequireAdministrator): winapp run . --no-build --detach --json

Before: An error occurred trying to start process '...\StarlightGUI.exe' with working directory '...'. The requested operation requires elevation.
After: StarlightGUI.exe requires administrator rights (its manifest sets requireAdministrator). Run winapp from an elevated terminal, or lower the app's UAC execution level for this configuration.

AudioPlaybackConnector2 (N0ahTM/AudioPlaybackConnector2) on an x64 PC: winapp run . -p Platform=ARM64 --detach --json

Before (after a 188 s build): Failed to prepare the Windows App Runtime: The Windows App Runtime (Framework + DDLM) for architecture 'arm64' is not registered and could not be installed, ...
After (1.7 s): AudioPlaybackConnector2.vcxproj targets arm64, which this x64 machine can't run. Run it on an arm64 machine, or build for this machine (-p Platform=x64).

FastCopy (HO-COOH/FastCopy, vcpkg manifest, no vcpkg integrate install): winapp run . --project FastCopy --detach --json

Before: Build failed (exit code 1). (after error C1083: Cannot open include file: 'boost/container/static_vector.hpp')
After: Build failed for FastCopy.vcxproj. Headers are missing and the project uses vcpkg (vcpkg.json), but vcpkg isn't integrated with MSBuild. Run 'vcpkg integrate install' once (e.g. from a Developer PowerShell), then try again.

AudioPlaybackConnector2 imports vcpkg.targets itself; it still builds and launches with no hint.

Related Issue

Follow-up to #680 / #984.

Type of Change

  • 🐛 Bug fix

Checklist

  • New tests added for new functionality (if applicable). Each fix has a test that fails without it.
  • Tested locally on Windows
  • docs/usage.md updated (if CLI commands changed)

Additional Notes

  • Tests: the WinApp.Cli.Tests project ran 7,335 tests with 0 failures.
  • Live checks with the fixed CLI:
    • PhotoEditor (Windows App SDK 1.5, 1.8 and 2.x) and Windowing work with run . from the solution or project folder, run <vcxproj>, run <sln>, --no-build and --no-launch.
    • Each launched app showed a window, confirmed with winapp ui screenshot.
  • Not run: vcpkg integrate install makes a persistent user-wide change on this shared machine. Instead, a FastCopy build with vcpkg's props/targets force-imported got past the missing headers.

A C++ Debug build lists the debug CRT as 'C:\Program Files %28x86%29\...\ucrtbased.dll'.
winapp checked that escaped path literally, so every such packaged app failed with
'The build did not produce 1 file(s) the recipe lists'.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…choices

- MSB8036: suggest 'winget install Microsoft.WindowsSDK.<the version the project needs>'
  instead of always 10.0.26100, which did not fix the build.
- When several C# apps make a solution or folder ambiguous, also list the C++ app
  projects; they lose auto-selection to C# apps but are valid --project choices.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@nmetulev Nikola Metulev (nmetulev) added the agent-preparing Agent is addressing feedback or completing required validation and CI label Oct 8, 2026
@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact Baseline Current Delta
CLI (ARM64) 57.68 MB 57.70 MB 📈 +12.5 KB (+0.02%)
CLI (x64) 57.71 MB 57.72 MB 📈 +12.5 KB (+0.02%)
MSIX (ARM64) 23.95 MB 23.95 MB 📈 +4.6 KB (+0.02%)
MSIX (x64) 25.42 MB 25.42 MB 📉 -0.9 KB (-0.00%)
NPM Package 49.95 MB 49.97 MB 📈 +19.8 KB (+0.04%)
NuGet Package 50.06 MB 50.07 MB 📈 +3.9 KB (+0.01%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 8250 passed, 37 skipped out of 8287 tests in 1112.9s (+12 tests, -310.0s vs. baseline)

Test Coverage

✅ 86.6% line coverage, 81.2% branch coverage · ✅ no change vs. baseline

CLI Startup Time

62ms median (x64, winapp --version) · ✅ no change vs. baseline

Try This Build

Installs the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 1030
Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 1030

Run winapp-pr with no arguments to pick from a list of open PRs.


Updated 2026-10-08 21:01:42 UTC · commit a918fe2 · workflow run

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@nmetulev
Nikola Metulev (nmetulev) marked this pull request as ready for review October 8, 2026 07:16
Copilot AI balanced review requested due to automatic review settings October 8, 2026 07:16
@nmetulev Nikola Metulev (nmetulev) added ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Oct 8, 2026
@nmetulev Nikola Metulev (nmetulev) added agent-preparing Agent is addressing feedback or completing required validation and CI and removed ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge labels Oct 8, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The fixes are focused, adequately tested, and no unresolved defects were found.

0 open findings

What changed in this PR

Fixes three winapp run issues affecting packaged C++ applications.

Changes:

  • Unescapes MSBuild recipe source paths before staging.
  • Suggests the Windows SDK version reported by MSBuild.
  • Includes runnable C++ projects in ambiguity choices.
File Description
ProjectRunService.Input.cs Lists runnable C++ project choices.
ProjectRunService.Cpp.cs Extracts the missing SDK version.
MsixService.Identity.cs Unescapes recipe source paths.
ProjectRunServiceCppTests.cs Covers selection and SDK diagnostics.
MsixServiceIdentityTests.cs Covers escaped recipe paths.

🧠 Review effort: Balanced


Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

@nmetulev Nikola Metulev (nmetulev) added ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Oct 8, 2026
… building, hint vcpkg integration

- An exe whose manifest requires administrator rights now says so instead of
  surfacing the raw 'requested operation requires elevation' error.
- A project-mode run targeting an architecture this machine can't run fails
  before the build; --no-launch and remote execution targets still build.
- A C++ build that can't find headers, has a vcpkg.json, and has no vcpkg
  MSBuild integration (_ZVcpkgRoot empty) suggests 'vcpkg integrate install'.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@nmetulev Nikola Metulev (nmetulev) added agent-preparing Agent is addressing feedback or completing required validation and CI and removed ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge labels Oct 8, 2026
--runtime outranks --arch, which outranks -p Platform, so suggesting a
lower-ranked option looped back to the same error.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@nmetulev

Nikola Metulev (nmetulev) commented Oct 8, 2026 •

Copy link
Copy Markdown
Member Author

Real-world C++ WinUI 3 test results

I ran winapp run on these projects from fresh clones, on an x64 PC with VS 2026 (v145 toolset, Windows SDK 26100/28000). Each test copy got its own package identity, and launched apps were checked with winapp ui screenshot. Each project was also built with plain MSBuild first, so failures that aren't ours are labeled as the project's own problem.

Project Layout Result with this PR Category Fixed here?
WindowsAppSDK-Samples PhotoEditor (WASDK 1.5 / 1.8 / 2.x) packaged, .sln + .vcxproj Before: fails after the build (escaped ucrtbased.dll path). After: ., project folder, .vcxproj, .sln, --no-build, --no-launch all work; window shown our bug ✅
WindowsAppSDK-Samples Windowing packaged Same bug before; all variants work after our bug ✅
WindowsAppSDK-Samples SelfContainedDeployment unpackaged All variants work; --no-launch is refused for unpackaged apps (by design) works –
YexuanXiao/PlayerWinRT packaged, root .slnx, project in src/, WASDK 1.3 All variants work (plain MSBuild needed SolutionDir; winapp sets it) works –
N0ahTM/AudioPlaybackConnector2 unpackaged, 4-project .slnx, vcpkg, x64/ARM64 --project or the project folder works. The repo root gives a clear "multiple runnable projects" error. -p Platform=ARM64 on x64 used to fail after a 3-minute build works; arm64-on-x64 was ours ✅ (refused up front)
BreeceW/WinUIEdit 17-project mixed C#/C++ .sln, WASDK 1.7 The --project choices left out the C++ apps; the SDK hint suggested the wrong winget package. The project needs SDK 22621 and the v143 toolset ours (2 messages) + the project's own ✅ messages
axodox/unpaint packaged, packages.config Needs SDK 22621 (hint now correct); with overrides, its signing certificate is missing the project's own ✅ hint
OpenStarlight/StarlightGUI unpackaged, PackageReference Builds; Debug|x64 requires administrator rights. Raw Windows error before; clear message now ours (message) ✅
HO-COOH/FastCopy 6-project .sln, vcpkg + packages.config, WASDK 1.8 Clear "multiple runnable projects" error at the root. Missing boost headers without vcpkg integrate install (plain MSBuild too); now explained environment prerequisite ✅ hint
sotanakamura/winui3-without-xaml unpackaged, no XAML, WASDK 1.2 Missing v143 toolset, with clear guidance; on v145, compiler error STL1011 the project's own –
henzfdev/HC-Player unpackaged, space in path third_party\libmpv-2.dll isn't in the repo (plain MSBuild fails too) the project's own –
sunjw/fhash C# app → C++/CLI + wapproj Clear "build it with MSBuild first" error (C# app referencing a C++ project) known limitation, tracked on #680 –

Not done here: friendlier wording for winapp run . at the root of a multi-sample repo (skipped). Mixed C#→C++ solutions stay on #680.

@nmetulev Nikola Metulev (nmetulev) added ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Oct 8, 2026
@zateutsch
Zach Teutsch (zateutsch) enabled auto-merge (squash) October 8, 2026 20:33
…estion

With --arch or -r plus a matching -p Platform, suggesting only the winning option
produced a pair the C++ build rejects as conflicting.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@nmetulev Nikola Metulev (nmetulev) added the agent-preparing Agent is addressing feedback or completing required validation and CI label Oct 8, 2026
@zateutsch
Zach Teutsch (zateutsch) merged commit dd88b2e into main Oct 8, 2026
39 checks passed
@zateutsch
Zach Teutsch (zateutsch) deleted the nmetulev-cpp-vcxproj-run-support branch October 8, 2026 23:27
Nikola Metulev (nmetulev) added a commit that referenced this pull request Oct 8, 2026
Conflicts:
- RunCommand.ProjectMode.cs: keep main's requireAdministrator message (#1030)
  and this branch's RunFailure.Describe for the other launch errors.
- FakeAppLauncherService.cs: keep main's LaunchExecutableThrows and this
  branch's environment parameter.
- winapp-ui-automation SKILL.md: main's 300-char description plus the
  winui-devtools pointer.

Also trims the winui-devtools description to the 300-char budget from #985.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@nmetulev Nikola Metulev (nmetulev) removed the ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge label Oct 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants