Fix MAUI launch queue handoff

[Gerald Versluis (jfversluis)]

Description

This extracts the MAUI build-queue and launch-handoff fix from #18591 into a focused PR so the queue behavior can be reviewed independently from the larger OTLP, DevTunnels, DCP lifecycle, readiness, and Foundry changes.

MAUI platform resources that share one project must serialize their pre-builds because MSBuild cannot safely build the same project concurrently. The existing launch handoff used dotnet build --no-restore /t:Run -p:NoBuild=true, which .NET SDK 10.0.201 rejects with NETSDK1085 because the Build target is still invoked while NoBuild=true.

This change preserves the shared project build queue while making the launch handoff platform-aware:

• Non-Android platforms launch with dotnet build --no-restore /t:Run -p:BuildDependsOn= -p:NoBuild=true. Clearing BuildDependsOn before setting NoBuild=true avoids NETSDK1085, and the queue is released when DCP reports Running so another platform can build while the launched app remains alive.
• Android keeps dotnet build --no-restore /t:Run because its Run target performs required fast-deploy/runtime upload work after compilation. Android retains the queue through Running and releases it when the short-lived Run process reaches a terminal or unavailable state.
• The launch handoff ignores the replayed pre-launch Building snapshot using Aspire's resource-state comparer, handles raw DCP Terminated locally, and has a bounded timeout so a failed deployment cannot hold the queue indefinitely.
• Existing build failure, stop, cancellation, restart, and per-project serialization behavior remains intact.

User-facing usage

No AppHost changes are required. Multiple platform resources for one MAUI project continue to use the existing APIs:

var mauiApp = builder.AddMauiProject("mauiapp", "../MauiApp/MauiApp.csproj");

mauiApp.AddMacCatalystDevice();
mauiApp.AddiOSSimulator();
mauiApp.AddAndroidEmulator();

The platforms build serially, but successfully launched non-Android apps no longer hold the queue for their full lifetime. Android holds it only until deployment and runtime upload complete.

Validation

Automated validation on rebased head 188909a89764483886786644219a7c4e18de5f1f against latest main at f721513cf34b4abdc5217ccb001b52ccf2008f4a:

• ./restore.sh
• MSBUILDTERMINALLOGGER=false dotnet build src/Aspire.Hosting.Maui/Aspire.Hosting.Maui.csproj --no-restore -m:1 — succeeded with 0 warnings and 0 errors
• Focused MTP command-shape, queue-handoff, failure, timeout, cancellation, and stop tests with quarantined and outerloop exclusions — 19 passed
• Complete Aspire.Hosting.Maui.Tests project with quarantined and outerloop exclusions — 183 passed
• git diff --check main...HEAD and the six-file allowlist check passed
• Final generic code review and Aspire architecture review reported no findings

Manual AppHost/device validation was completed before the conflict-free latest-main rebase on the equivalent queue changes at dc8225702b9c0bdf4c8641f13cb9e24cb383f88c:

• Mac Catalyst and iOS released the queue at Running while both /t:Run processes and apps remained alive
• Non-Android launches used the expected BuildDependsOn/NoBuild command shape without NETSDK1085
• Android queued behind iOS, retained the queue while Running and deploying, and released it only after /t:Run exited
• The Android app remained foregrounded and alive after its resource became Finished
• Mac Catalyst stop/start rejoined the queue successfully
• Build failure, launch-handoff timeout, and cancellation released the queue

The first cold Android build exceeded the existing 10-minute build timeout under local disk/cache pressure. A direct incremental pre-build completed in 39.55 seconds and the real retry then passed. Local validation also required linking the already-installed MAUI workload packs into the worktree SDK and suppressing the playground's pre-existing NU1605 package mismatch.

After rebasing, the MAUI hosting project build and complete 183-test MAUI suite were rerun successfully, followed by fresh generic and Aspire architecture reviews with no findings.

Related focused work

#19386 is the sibling follow-up containing only the MAUI OTLP dev-tunnel endpoint resolution and Android/iOS environment refresh extracted from #18591. It intentionally excludes long-running DevTunnel watcher reconciliation, stale-port cleanup, shared allocation serialization, and broader DCP/readiness/Foundry lifecycle changes.

Fixes # (issue)

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 19383

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 19383"

[Copilot]

Pull request overview

Updates MAUI platform launch handoff while preserving serialized builds for shared projects.

Changes:

• Uses platform-specific MAUI Run commands and queue-release policies.
• Adds bounded, state-aware lock release handling.
• Expands regression tests and documentation.

Show a summary per file

File	Description
src/Aspire.Hosting.Maui/Annotations/MauiBuildInfoAnnotation.cs	Stores the platform lock-release policy.
src/Aspire.Hosting.Maui/Lifecycle/MauiBuildQueueEventSubscriber.cs	Implements state-aware, timed queue handoff.
src/Aspire.Hosting.Maui/MauiPlatformHelper.cs	Configures Android and non-Android launch behavior.
src/Aspire.Hosting.Maui/README.md	Documents platform-specific queue semantics.
tests/Aspire.Hosting.Maui.Tests/MauiBuildQueueTests.cs	Tests handoff states, timeout, and cancellation.
tests/Aspire.Hosting.Maui.Tests/MauiPlatformExtensionsTests.cs	Verifies platform command shapes and policies.

Review details

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.