Blazor hosting changes for WebAssembly debugging

[maraf]

This PR is a subset of POC in #17559. It includes changes to blazor hosting and associated tests.

Description

Adds browser debugging support for Blazor WebAssembly apps to Aspire.Hosting.Blazor:

• New BrowserDebuggerHelper that registers a hidden child "browser debugger" resource parented to the Blazor gateway and adds a Debug in Browser command to the WASM app resource, and watches for the debugger stopping.
• AddBlazorGateway / gateway registration now accepts an optional debuggerBrowser parameter (defaults to "msedge", also supports "chrome") that is passed through to the WASM app registration, inspired by the JavaScript app debugger support.
• BlazorHostedExtensions resolves the Blazor WebAssembly client project path from the server project's references so the debug bridge can locate the WASM BCL assemblies in the client's output directory.
• Debugger registration is skipped in publish mode.
• Adds unit tests covering BrowserDebuggerHelper, BlazorHostedExtensions, and the WithBlazorApp flows.

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 -- 18928

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Adds a run-only browser-debugger companion for hosted and gateway Blazor WebAssembly applications.

Changes:

• Adds debugger resources, dashboard commands, and launch configuration.
• Resolves hosted WASM client project paths.
• Adds unit coverage for debugger registration and lifecycle behavior.

Reviewed changes

Copilot reviewed 20 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Aspire.Hosting.Blazor/BrowserDebuggerHelper.cs	Implements debugger resource and commands.
src/Aspire.Hosting.Blazor/BlazorHostedExtensions.cs	Adds hosted-client debugger integration.
src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs	Adds gateway debugger configuration.
src/Aspire.Hosting.Blazor/Aspire.Hosting.Blazor.csproj	Adds shared debugger sources.
tests/Aspire.Hosting.Blazor.Tests/BrowserDebuggerHelperTests.cs	Tests debugger-stop observation.
tests/Aspire.Hosting.Blazor.Tests/BlazorHostedExtensionsTests.cs	Tests hosted debugger integration.
tests/Aspire.Hosting.Blazor.Tests/WithBlazorAppTests.cs	Tests gateway debugger integration.
tests/Aspire.Hosting.Blazor.Tests/Aspire.Hosting.Blazor.Tests.csproj	Links shared async test helpers.

Comments suppressed due to low confidence (5)

src/Aspire.Hosting.Blazor/BrowserDebuggerHelper.cs:47

• These derived names can exceed Aspire's 64-character resource-name limit even when both user-supplied names are individually valid. AddResource validates the generated name and will reject, for example, two 28-character names plus this suffix. Apply the established NameValidationPolicyAnnotation.None policy used by other internal suffixed helpers such as project rebuilders.

        var debuggerResourceName = relativePath is not null
            ? $"{parentResource.Name}-{commandTarget.Resource.Name}-debugger"
            : $"{parentResource.Name}-wasm-debugger";

src/Aspire.Hosting.Blazor/BrowserDebuggerHelper.cs:96

• web_root is copied directly to the VS Code pwa-* debug configuration's webRoot (extension/src/debugger/languages/browser.ts:24-30), which requires a directory. Passing the .csproj file path makes source-map resolution root beneath a file and prevents the debugger from locating sources. Use the already computed clientProjectDir here and update the assertions accordingly.

                        WebRoot = clientProjectPath,

src/Aspire.Hosting.Blazor/BrowserDebuggerHelper.cs:111

• This check does not serialize command execution. ResourceCommandService invokes callbacks without a per-resource lock, so two concurrent requests can both observe false, start the debugger twice, and concurrently cancel/dispose/reassign watcherCts; one request can then access a disposed CTS. Guard the session state and CTS transitions with a semaphore or other atomic synchronization before the first await.

                if (debugSessionActive)
                {
                    return CommandResults.Success();
                }

src/Aspire.Hosting.Blazor/BrowserDebuggerHelper.cs:168

• The watcher is canceled before StopResourceAsync succeeds. If stopping is canceled or throws, ResourceCommandService returns a failed/canceled result while debugSessionActive remains true and no watcher remains to clear it when the browser later exits, leaving command state stale. Keep the watcher alive until stop succeeds, or restore/restart it on the failure path.

                // Cancel the watcher so it doesn't race with our state reset.
                await watcherCts.CancelAsync().ConfigureAwait(false);

                var dcpInstanceName = GetDcpInstanceName(debuggerResource);
                var orchestrator = context.ServiceProvider.GetRequiredService<ApplicationOrchestrator>();
                await orchestrator.StopResourceAsync(dcpInstanceName, context.CancellationToken).ConfigureAwait(false);

src/Aspire.Hosting.Blazor/Aspire.Hosting.Blazor.csproj:38

• $(SharedDir) resolves to src/Shared, but neither BrowserDebuggerResource.cs nor BrowserLaunchConfiguration.cs exists there; both files remain under src/Aspire.Hosting.JavaScript. These compile items therefore reference missing source files and the project cannot build. Move the shared implementations into src/Shared (updating JavaScript too) or include an existing source path.

    <Compile Include="$(SharedDir)BrowserDebuggerResource.cs" Link="BrowserDebuggerResource.cs" />
    <Compile Include="$(SharedDir)BrowserLaunchConfiguration.cs" Link="BrowserLaunchConfiguration.cs" />

[Copilot]

Pull request overview

Copilot reviewed 20 out of 25 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (6)

src/Aspire.Hosting.Blazor/Aspire.Hosting.Blazor.csproj:35

• Aspire.Hosting does not grant InternalsVisibleTo to Aspire.Hosting.Blazor (its friend list only includes JavaScript, Go, Python, tests, etc.). Removing the source-shared StringComparers therefore makes the existing use in BlazorHostedExtensions inaccessible, and the new helper also calls internal Hosting APIs such as TryGetInstances; the project will fail with CS0122 even after the missing source files are fixed. Add the required friend assembly or avoid those internal dependencies.

    <!-- StringComparers and KnownRelationshipTypes are provided by the referenced Aspire.Hosting
         assembly (which source-shares them and exposes internals here via InternalsVisibleTo),
         so they must not be source-shared again or they would conflict (CS0436). -->

src/Aspire.Hosting.Blazor/BlazorHostedExtensions.cs:83

• Because IsInitialized returns here, debuggerBrowser from every proxy call after the first is silently ignored. For example, ProxyBlazorService(service) followed by ProxyBlazorTelemetry(debuggerBrowser: "chrome") still creates an Edge debugger despite the explicit Chrome argument. Make browser selection a once-per-host API, reject conflicting values, or store last-wins configuration and materialize the debugger from the final value.

        if (annotation.IsInitialized)
        {
            return;

src/Aspire.Hosting.Blazor/BlazorHostedExtensions.cs:185

• Normalize the ProjectReference path before resolving it. On Linux, Path.Combine does not treat backslashes as separators, so the repository's own BlazorHosted.csproj reference (..\BlazorHosted.Client\...) fails File.Exists and silently falls back to the server project, preventing hosted WASM debugging. PathNormalizer.NormalizePathForCurrentPlatform already handles both separators.

                var fullPath = Path.GetFullPath(Path.Combine(serverDir, relPath!));

src/Aspire.Hosting.Blazor/BrowserDebuggerHelper.cs:110

• This boolean check is not a concurrency guard. ResourceCommandService invokes command callbacks without serialization, so two requests can both observe false, start the debugger twice, and race while canceling/disposing/replacing watcherCts; start and stop can race similarly. Serialize both handlers with a shared gate or use an atomic state machine rather than relying on dashboard command visibility.

                if (debugSessionActive)
                {
                    return CommandResults.Success();

playground/BlazorHosted/BlazorHosted.Client/BlazorHosted.Client.csproj:21

• The linked vscode-dotnettools#3002 was fixed and verified in C# 2.141.13/C# Dev Kit 3.14.215, then closed as completed on 2026-05-15 with guidance to use current stable extensions. Keeping this workaround now disables WebCIL for every build based on a resolved tooling regression; remove it or link an active hosted-mode issue that still reproduces with supported versions.

    <!-- Workaround: monovsdbg_wasm WebCIL parser fails in hosted mode.
         Serving plain .dll files bypasses the issue.
         Tracking: https://github.com/microsoft/vscode-dotnettools/issues/3002 -->
    <WasmEnableWebcil>false</WasmEnableWebcil>

src/Aspire.Hosting.Blazor/BrowserDebuggerHelper.cs:47

• Concatenating two valid resource names plus this suffix does not guarantee a valid or unique derived name. Aspire resource names may each be 64 characters, so enabling debugging for longer valid gateway/app names makes AddResource throw because the debugger name exceeds 64 characters; delimiter ambiguity can also collide across different parent/child pairs. Generate a bounded, collision-resistant internal name instead.

        var debuggerResourceName = relativePath is not null
            ? $"{parentResource.Name}-{commandTarget.Resource.Name}-debugger"
            : $"{parentResource.Name}-wasm-debugger";