Export Dotnet Blazor gateway APIs to polyglot AppHosts

[Karol Zadora-Przylecki (karolz-ms)]

Description

Polyglot AppHosts can now use the DotnetProjectResource-backed Blazor gateway APIs introduced for Project V2. These methods were previously marked [AspireExportIgnore] even though their parameter and return types are ATS-compatible. This follows Sebastien's feedback in the API surface review.

AddDotnetProjectBlazorGateway is now exported directly. The DotnetProjectResource overload of WithBlazorClientApp uses the distinct withDotnetProjectBlazorClientApp capability ID to avoid colliding with the existing ProjectResource overload, while retaining withBlazorClientApp as the generated method name on the new resource handle.

The existing Blazor validation AppHosts now exercise both APIs in TypeScript, Go, Java, and Python. The Project V2 feature plan also records the additive capabilities and the unchanged run-only behavior; publishing this gateway variant still fails fast until DotnetProjectResource supports the container-files pipeline.

User-facing usage

C# AppHost:

var client = builder.AddBlazorWasmProject<Projects.Client>("client");

builder.AddDotnetProjectBlazorGateway("gateway")
    .WithBlazorClientApp(client);

TypeScript AppHost:

const client = await builder.addBlazorWasmProject("client", "../Client/Client.csproj");
const gateway = await builder.addDotnetProjectBlazorGateway("gateway");

await gateway.withBlazorClientApp(client);

Validation

• Aspire.Hosting.Blazor builds with zero analyzer warnings or errors.
• AddDotnetProjectBlazorGatewayTests passes all 3 tests.
• Regenerated TypeScript, Go, Java, and Python SDK fixtures compile successfully.
• Generated api/*.cs, *.ats.txt, and .aspire/modules files are not included.

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

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Exports the Project V2 Blazor gateway APIs to polyglot AppHosts while preserving run-only behavior.

Changes:

• Adds distinct ATS capability IDs with consistent generated method names.
• Validates generated APIs across TypeScript, Python, Java, and Go.
• Updates the Project V2 plan.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs	Enables polyglot exports.
tests/PolyglotAppHosts/Aspire.Hosting.Blazor/TypeScript/apphost.mts	Exercises TypeScript APIs.
tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Python/apphost.py	Exercises Python APIs.
tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Java/AppHost.java	Exercises Java APIs.
tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Go/apphost.go	Exercises Go APIs.
docs/plans/project-v2-csharpprogram-watch.md	Documents capabilities and validation.

[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.

[Karol Zadora-Przylecki (karolz-ms)]

Code review of the polyglot export flip. The capability IDs, MethodName override, and analyzer/codegen collision handling all check out — my findings are confined to the generated SDK documentation that these two exports now make user-facing, plus one stale attribute reason.

4 issues: 3 generated-documentation problems, 1 stale comment.

[Karol Zadora-Przylecki (karolz-ms)]

Review of the polyglot export + runtime-asset packaging change.

I packed Aspire.Hosting.Blazor locally to confirm the layout change: the nupkg carries both buildTransitive/<tfm>/Scripts/* and lib/<tfm>/Scripts/* with identical content and zero NuGet warnings. I also traced IntegrationLoadContext -> IntegrationPackageProbeManifest -> NuGetPackageAssetResolver and confirmed that for a package-backed integration Assembly.Location resolves into the extracted global-packages lib/<tfm> folder, so GetScriptPath() finds the scripts. The changed tests all pass locally (AddDotnetProjectBlazorGatewayTests 3/3, AspireHostingBlazorPackageContainsScriptsForBuildAndDirectLoading 1/1, RealMapBlazorRuntimeAssetChangeRunsPackageAndPolyglotRegressions 1/1), and the new E2E script's jq filter matches the real describe --format json shape.

Two findings: one test-robustness issue and one accuracy issue in the packaging comment / plan doc.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

[Karol Zadora-Przylecki (karolz-ms)]

Review of the polyglot export + runtime-asset packaging change.

I validated the mechanism locally rather than reading the diff alone: packed Aspire.Hosting.Blazor and confirmed the nupkg carries both buildTransitive/<tfm>/Scripts/* and lib/<tfm>/Scripts/* byte-identical with zero NuGet warnings; traced IntegrationLoadContext -> IntegrationPackageProbeManifest to confirm package-backed integrations load straight from the NuGet cache so Scripts/ really does sit next to Assembly.Location; ran the 3 Blazor unit tests, the new AspireHostingBlazorPackageContainsScriptsForBuildAndDirectLoading, and the new RealMapBlazorRuntimeAssetChangeRunsPackageAndPolyglotRegressions (all pass); and confirmed all four polyglot playground scripts are compile-only, so the publish fail-fast can't break the polyglot job. Not regenerating *.ats.txt is correct per docs/ci/typescript-api-compat.md.

3 issues: 1 correctness/API-contract gap (with the matching missing regression test), 2 test-coverage/diagnostics nits.

The headline one is that the publish fail-fast guard sits on AddDotnetProjectBlazorGateway but not on the WithBlazorClientApp overload this PR exports, so the "publishing still fails fast" claim in the description only holds for one of the two now-public entry points.

[github-actions]

Tests selector (audit mode)

The full test matrix and all jobs still run in audit mode. The tests and jobs below are what selective CI would run under enforcement.

9 / 102 test projects · 4 jobs, from 14 changed files.

Selected test projects (9 / 102)

Aspire.Cli.EndToEnd.Tests, Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Dotnet.Tests, Aspire.Hosting.Radius.Tests, Aspire.Hosting.Tests, Aspire.Playground.Tests, Infrastructure.Tests

Selected jobs (4)

cli-starter, extension-e2e, polyglot, typescript-api-compat

---

How these were chosen — grouped by what changed

🧪 tests/Aspire.Hosting.Tests/MSBuildTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests
→ 4 via the project graph: Aspire.Hosting.Azure.Kubernetes.Tests (2 hops), Aspire.Hosting.Azure.Tests, Aspire.Hosting.Dotnet.Tests, Aspire.Hosting.Radius.Tests

🔧 src/Aspire.Hosting.Blazor/Aspire.Hosting.Blazor.csproj (changed source)
→ 3 directly: Aspire.Cli.EndToEnd.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Tests
→ 1 via the project graph: Aspire.Playground.Tests

🔧 src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs (changed source)
→ 3 directly: Aspire.Cli.EndToEnd.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Tests

🔧 src/Aspire.Hosting.Blazor/targets/GenerateScripts.targets (changed source)
→ 3 directly: Aspire.Cli.EndToEnd.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Tests

📄 .github/workflows/polyglot-validation/test-python-playground.sh (changed)
→ 1 directly: Infrastructure.Tests

📄 eng/github-ci/test-trigger-map.yml (changed)
→ 1 directly: Infrastructure.Tests

🧪 tests/Aspire.Cli.EndToEnd.Tests/TypeScriptBlazorGatewayTests.cs (changed test)
→ 1 directly: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Hosting.Blazor.Tests/AddDotnetProjectBlazorGatewayTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Blazor.Tests

🧪 tests/Infrastructure.Tests/TestTriggerMap/SelectTestsAcceptanceTests.cs (changed test)
→ 1 directly: Infrastructure.Tests

Job reasons

Job	Triggered by
cli-starter	selected test Aspire.Cli.EndToEnd.Tests
extension-e2e	• src/Aspire.Hosting.Blazor/Aspire.Hosting.Blazor.csproj, src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs, src/Aspire.Hosting.Blazor/targets/GenerateScripts.targets, tests/Aspire.Cli.EndToEnd.Tests/TypeScriptBlazorGatewayTests.cs • affected project Aspire.Hosting.Blazor
polyglot	.github/workflows/polyglot-validation/test-python-playground.sh, src/Aspire.Hosting.Blazor/Aspire.Hosting.Blazor.csproj, src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs, src/Aspire.Hosting.Blazor/targets/GenerateScripts.targets, tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Go/apphost.go, tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Java/AppHost.java, tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Python/apphost.py, tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Python/validate_generated_sdk.py, tests/PolyglotAppHosts/Aspire.Hosting.Blazor/TypeScript/apphost.mts
typescript-api-compat	affected project Aspire.Hosting.Blazor

---

Selection computed for commit 61c2125.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

[Karol Zadora-Przylecki (karolz-ms)]

PR Testing Report

PR Information

• PR Number: Export Dotnet Blazor gateway APIs to polyglot AppHosts #19026
• Title: Export Dotnet Blazor gateway APIs to polyglot AppHosts
• Head Commit: 61c2125479aaec4ed62363ce70ae22e7123def95
• Tested At: 2026-08-20T21:58:13Z
• Execution Target: Local macOS temp directory; no container runtime was required

Artifact Version Verification

• Expected Commit: 61c2125479aaec4ed62363ce70ae22e7123def95
• Installed Version: 13.6.0-pr.19026.g61c21254
• Artifact Source: PR workflow run 32415856204
• Status: ✅ Verified

The installed CLI reports the PR head short commit 61c21254.

Changes Analyzed

Files Changed

• .github/workflows/polyglot-validation/test-python-playground.sh
• docs/plans/project-v2-csharpprogram-watch.md
• eng/github-ci/test-trigger-map.yml
• src/Aspire.Hosting.Blazor/Aspire.Hosting.Blazor.csproj
• src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs
• src/Aspire.Hosting.Blazor/targets/GenerateScripts.targets
• tests/Aspire.Cli.EndToEnd.Tests/TypeScriptBlazorGatewayTests.cs
• tests/Aspire.Hosting.Blazor.Tests/AddDotnetProjectBlazorGatewayTests.cs
• tests/Aspire.Hosting.Tests/MSBuildTests.cs
• tests/Infrastructure.Tests/TestTriggerMap/SelectTestsAcceptanceTests.cs
• tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Go/apphost.go
• tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Java/AppHost.java
• tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Python/apphost.py
• tests/PolyglotAppHosts/Aspire.Hosting.Blazor/Python/validate_generated_sdk.py
• tests/PolyglotAppHosts/Aspire.Hosting.Blazor/TypeScript/apphost.mts

Change Categories

• Hosting/API export changes
• Package layout changes
• TypeScript, Go, Java, and Python generated SDK fixture changes
• CLI end-to-end test changes
• GitHub Actions CI helper and selective-test routing changes
• Dashboard changes
• Client/component integration changes
• Template changes
• VS Code extension changes
• Azure DevOps changes

Test Scenarios Executed

Scenario 1: PR artifact identity and Blazor package layout

Objective: Verify the tested CLI and NuGet package contain the PR head and the new direct-load script layout.

Coverage Type: Artifact/package validation

Status: ✅ Passed

Steps:

1. Installed PR Export Dotnet Blazor gateway APIs to polyglot AppHosts #19026 with the repository dogfood installer into an isolated temp directory.
2. Verified the installed CLI version contains g61c21254.
3. Inspected Aspire.Hosting.Blazor.13.6.0-pr.19026.g61c21254.nupkg.
4. Compared both copies of Gateway.cs and PrefixEndpoints.cs.

Observations:

• The package contains both scripts under buildTransitive/net8.0/Scripts/.
• The package also contains both scripts under lib/net8.0/Scripts/.
• Each direct-load copy is byte-identical to its build-transitive copy.

Evidence:

• version.txt
• version-status.txt
• package-layout.txt
• install.log

Scenario 2: TypeScript DotnetProject Blazor gateway runtime

Objective: Verify a TypeScript AppHost can compile and invoke the two exported APIs, run the gateway, and serve a Blazor WASM client.

Coverage Type: Happy-path runtime

Status: ✅ Passed

Steps:

1. Created a fresh TypeScript AppHost with the PR CLI.

2. Added Aspire.Hosting.Blazor version 13.6.0-pr.19026.g61c21254 from the PR hive.

3. Created a fresh .NET 10 Blazor WASM project.

4. Added:

   const client = await builder.addBlazorWasmProject('client', './Client/Client.csproj');
   const gateway = await builder.addDotnetProjectBlazorGateway('gateway');
   await gateway.withBlazorClientApp(client);

5. Ran aspire restore and compiled the generated TypeScript SDK with ESLint and tsc.

6. Started the AppHost with canonical macOS paths, waited for gateway, and fetched /client/.

7. Verified the response contains <title>Client</title> and _framework/blazor.webassembly.

Observations:

• The generated TypeScript SDK exposes both new APIs with the expected names.
• The gateway resource reached Running and served the Blazor client on the first HTTP attempt.
• The gateway loaded Gateway.cs from the package's new lib/net8.0/Scripts location.
• An initial run used macOS's logical /var/... temp path while the process resolved /private/var/...; that path-alias mismatch confused Razor/MSBuild. Re-running the unchanged scenario with realpath-canonicalized paths passed. This was a local temp-path artifact, not a PR behavior failure.

Evidence:

• scenario-typescript/setup.log
• scenario-typescript/codegen-build.log
• scenario-typescript/start-canonical.json
• scenario-typescript/wait-canonical.log
• scenario-typescript/gateway-canonical.json
• scenario-typescript/gateway-canonical-logs.txt
• scenario-typescript/runtime-verification-canonical.txt
• scenario-typescript/client-index-canonical.html

Scenario 3: Python generated SDK and CI validator behavior

Objective: Verify the Python SDK exposes the new members and the changed CI script invokes its fixture validator without losing existing settings.

Coverage Type: Generated API and boundary/failure-path validation

Status: ✅ Passed

Steps:

1. Created a fresh Python AppHost configuration pinned to the PR channel and package version.
2. Ran aspire restore.
3. Compiled the AppHost, validator, and generated Python module sources.
4. Imported the generated module and verified:
   • DistributedApplicationBuilder.add_dotnet_project_blazor_gateway
   • DotnetProjectResource.with_blazor_client_app
5. Ran the exact PR-head test-python-playground.sh in a one-fixture harness with the approved PyPI proxy.
6. Seeded .aspire/settings.json with an existing channel and sentinel property.
7. Verified the script restored the settings file byte-for-byte after both an intentionally failed harness attempt and the successful validation run.

Observations:

• The generated API members are present.
• The changed script printed generated SDK API validation... and reported Aspire.Hosting.Blazor passed.
• The script preserved existing project channel/settings state across success and failure cleanup paths.

Expected Boundary Outcome: Temporary channel pinning must not overwrite a fixture's prior settings.

Evidence:

• scenario-python/python-sdk-validation.log
• scenario-python-script-harness/script-run-proxy.log
• scenario-python-script-harness/settings-preservation-proxy.txt
• scenario-python-script-harness/settings-before-proxy.json

Scenario 4: Unsupported publish path

Objective: Verify the exported DotnetProject gateway still fails fast in publish mode rather than producing an incomplete deployment.

Coverage Type: Unhappy path

Status: ✅ Passed

Steps:

1. Created a second fresh TypeScript AppHost and Blazor WASM project.
2. Restored and compiled the generated TypeScript SDK.
3. Ran aspire publish non-interactively.

Expected Unhappy-Path Outcome: A nonzero exit code and a clear unsupported-publish error directing users to addBlazorGateway.

Observations:

• aspire publish exited with code 6.
• The capability error identified addDotnetProjectBlazorGateway.
• The message stated: Publishing a DotnetProjectResource-backed Blazor gateway is not supported yet. Use addBlazorGateway for publish scenarios.

Evidence:

• scenario-publish/codegen-build.log
• scenario-publish/publish.log
• scenario-publish/publish-exit.txt
• scenario-publish/publish-expected-error.txt

CI Infrastructure Validation

GitHub Actions

What runs on this PR:

• ci.yml invoked tests.yml, which invoked the reusable polyglot-validation.yml.
• Dockerfile.python copied and executed the changed test-python-playground.sh.
• The selective-test map routed the Blazor source/asset changes to Aspire.Hosting.Tests, Aspire.Cli.EndToEnd.Tests, and job:polyglot.
• All targeted checks completed successfully:
  • Infrastructure
  • Hosting.Blazor on Ubuntu and Windows
  • Hosting-1 on Windows after the automatic transient retry
  • TypeScript Blazor gateway CLI E2E
  • Go, Java, Python, and TypeScript polyglot validation

Automated tests:

• Infrastructure Tests: 639 passed, 0 failed
• TypeScript Blazor gateway CLI E2E: 1 passed, 0 failed
• Python polyglot fixtures: 55 passed, 0 failed
• Go polyglot fixtures: 54 passed, 0 failed
• Java polyglot fixtures: 55 passed, 0 failed
• TypeScript polyglot fixtures: 59 passed, 0 failed

Results validation:

• Python job log explicitly shows Testing: Aspire.Hosting.Blazor, generated SDK API validation..., and OK: Aspire.Hosting.Blazor passed.
• Go, Java, and TypeScript job logs explicitly show the Blazor fixture restored/compiled and passed.
• The focused Ubuntu CLI E2E executed exactly one TypeScriptBlazorGatewayTests test and passed; the local macOS runtime scenario independently verified the same HTTP behavior.
• The package layout was validated directly from the downloaded PR NuGet artifact.
• The first Windows Hosting-1 job lost communication with its hosted runner during the test step and produced no test failure artifact. Its annotation matched the repository's transient-rerun rule, and automatic run attempt 2 completed that job successfully.

Manual triggers: None. Every affected workflow path was exercised by this PR's own CI run, so an additional dispatch would duplicate coverage.

Dependency graph:

• test-python-playground.sh → Dockerfile.python → polyglot-validation.yml → tests.yml → ci.yml.
• test-trigger-map.yml → tools/SelectTests / .github/actions/select-tests → selected test projects and polyglot job flags.
• No artifact name or producer/consumer layout changed outside the Blazor NuGet package itself; that package layout was inspected directly.

Coverage-loss audit:

• The trigger-map change is additive.
• No workflow trigger, permission, required-check dependency, matrix, or artifact producer was removed or narrowed.
• The expected additional Hosting, CLI E2E, Infrastructure, and polyglot jobs were present in the PR run.

gh-aw: Not applicable.

Failure-modes scan:

• No on:, permission, fork-context, reusable-workflow contract, generated lock file, or cross-workflow artifact change.
• The changed shell script ran in the real PR Python validation job and in a focused local harness.
• Channel pinning selected the PR package identity and restored prior settings on success and failure.

Azure DevOps

Not applicable; the PR does not change Azure DevOps pipeline infrastructure.

Summary

Scenario	Status	Notes
Artifact identity and package layout	✅ Passed	PR commit matched; both script layouts present and identical
TypeScript generated SDK and runtime	✅ Passed	New APIs compiled; gateway served the Blazor client
Python generated SDK and validator	✅ Passed	Both members present; validator and settings cleanup worked
Unsupported publish path	✅ Passed	Exit code 6 with the documented capability error
CI infrastructure validation	✅ Passed	Targeted Infrastructure, Hosting, E2E, and polyglot jobs passed

Overall Result

✅ PR VERIFIED

The changed API exports, package layout, TypeScript runtime path, Python generated SDK validation, unsupported publish guard, and selective CI routing all behaved as intended.

At report time, automatic CI run attempt 2 had 376 passing checks, no failed checks, one skipped check, and only the aggregate Final Test Results check still queued. The retried Windows Hosting-1 job had completed successfully.

[Sébastien Ros (sebastienros)]

I'll refactor the python validation next

[aspire-repo-bot]

Pull request created: #1564

Generated by PR Documentation Check · auto · 66.2 AIC · ⌖ 12.3 AIC · ⊞ 19.6K

[aspire-repo-bot]

📝 Documentation has been drafted in microsoft/aspire.dev#1564 targeting release/17.0.

Added a new section to blazor-hosting.mdx documenting the newly-exported DotnetProjectResource-backed Blazor gateway APIs (AddDotnetProjectBlazorGateway/addDotnetProjectBlazorGateway and the WithBlazorClientApp/withBlazorClientApp overload) for polyglot AppHosts, including C#/TypeScript examples, the ASPIREDOTNETPROJECT001 experimental caveat, and the run-only/publish-fails-fast limitation.

• Modified: src/frontend/src/content/docs/integrations/dotnet/blazor-hosting.mdx

Note

This draft PR needs human review before merging.