Skip to content

Add aspire sdk export -l go (Go API reference exporter) - #21195

Merged
David Pine (IEvangelist) merged 14 commits into
mainfrom
ievangelist-go-api-exporter
Oct 30, 2026
Merged

David Pine (IEvangelist) merged 14 commits into
mainfrom
ievangelist-go-api-exporter

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

Note

Merge order: no PR must land before this one. It overlaps #21197, which adds the same AtsTypeSystemCompatibility.cs and changes two generator members that this exporter calls. They merge without textual conflicts, but whichever lands second needs a two-line fix-up in AtsGoCodeGenerator.ApiProjection.cs, described in #21197.

Description

aspire sdk export --language go fails today with "no IApiReferenceExporter", because only TypeScript ships an exporter (#19032). This adds the Go exporter, so the Go API reference can be produced by the same code that generates the Go SDK.

aspire.dev builds its Go API reference from aspire sdk dump (microsoft/aspire.dev#1917). The Go mode of its AtsJsonGenerator re-implements the Go generator's naming and type mapping, so it can drift from what AtsGoCodeGenerator really emits, and a dump cannot see the surface the generator writes by hand:

  • the synthesized Build() on the builder
  • the InteractionInputCollection helpers (Get, Required, Value, RequiredValue)
  • Err() on every handle and ToMap() on options structs
  • the hand-written base.go runtime types
  • the trailing opts ...*XxxOptions flattening and the callback func types

The export projects through the generator's own naming and type-mapping code, so aspire.dev can consume aspire sdk export -l go for signatures instead of re-deriving them.

Part of #21115.

What changes

  • AtsGoApiReferenceExporter (new) implements IApiReferenceExporter for Go. It is a separate type from AtsGoCodeGenerator on purpose, as in the TypeScript exporter. Aspire.TypeSystem is force-shared with a frozen AssemblyVersion, so an older CLI binds this assembly but its copy of Aspire.TypeSystem has no IApiReferenceExporter, and a type that implements the interface cannot load there. CodeGeneratorResolver salvages the loadable types, so such a CLI keeps generating Go and only loses the export.
  • AtsGoCodeGenerator becomes partial (one word in AtsGoCodeGenerator.cs). The new AtsGoCodeGenerator.ApiProjection.cs builds the export model with the generator's own naming and type-mapping helpers, so there is no second copy of the Go rules to keep in sync.
  • GoDeclarationScanner reads the hand-written Go that the generator itself emits (the base.go runtime and the builder entry point) instead of keeping a hand-maintained list, so that surface cannot drift either.
  • GoApiModel and GoApiExportWriter hold the model and write the document. The writer builds a JsonNode tree and the exporter returns JsonDocument.Parse(...).RootElement.Clone(), the AOT-safe pattern the TypeScript exporter uses (no reflection serializer). Line endings are normalized to LF and items, declarations and members come out in a fixed order, so the output is reproducible byte for byte.
  • src/Shared/CodeGeneration/AtsTypeSystemCompatibility.cs (new, linked into the Go project) is the TypeScript generator's version-skew probe in the shared folder. It reads AtsCapabilityInfo.IsExperimental reflectively so a newer generator still runs against an older Aspire.TypeSystem. The TypeScript project keeps its own copy.
  • CLI: the --language help of aspire sdk export reads (e.g., typescript, go), and docs/specs/cli-output-formats.md describes the Go export next to the TypeScript one. Go resolves through the same language discovery as the other languages, so it needs the existing experimentalPolyglotGo feature.
  • All new types are internal, so there is no public API change. About 2,300 lines are product code and 1,700 are tests and snapshots.

Export shape

The envelope matches the TypeScript export so one consumer can read both: schemaVersion (1), language (go), generator (name, version), package (name, version, and Go's importPath), modules[] (name, items[]) and declarations[] (id, owningAssembly, content).

  • items[].kind is interface, augmentation (members a package adds to a type that another package declares), dto, options, enum, variable, function or type.
  • members[].kind is method, field or constant. Every member has the exact Go text in declaration. Capability-backed members carry capabilityId, and members that the generator writes itself are marked synthesized. Methods also carry errorModel (none, returned or deferred), experimental and deprecated markers where they apply, and an options block (the struct type and its fields) when the method takes the trailing opts ...*XxxOptions.

Trimmed excerpt of the Redis export. AddRedis shows the trailing options flattening and ToMap() shows a synthesized member:

{
  "id": "DistributedApplicationBuilder.AddRedis",
  "kind": "method",
  "name": "AddRedis",
  "declaration": "AddRedis(name string, options ...*AddRedisOptions) RedisResource",
  "capabilityId": "Aspire.Hosting.Redis/addRedis",
  "returnType": "RedisResource",
  "errorModel": "deferred",
  "parameters": [
    { "name": "name", "type": "string", "optional": false }
  ],
  "options": {
    "typeName": "AddRedisOptions",
    "fields": [
      { "name": "Port", "type": "*float64", "optional": true, "jsonName": "port" },
      { "name": "Password", "type": "*ParameterResource", "optional": true, "jsonName": "password" }
    ]
  }
}
{
  "id": "AddRedisOptions.ToMap",
  "kind": "method",
  "name": "ToMap",
  "declaration": "ToMap() map[string]any",
  "returnType": "map[string]any",
  "errorModel": "none",
  "synthesized": true
}

Sample exports

Produced end to end with a Debug-built CLI from this checkout. The integration packages restore from NuGet, while Aspire.Hosting and the Go generator are this checkout's.

Export Items Members Synthesized members Size
Aspire.Hosting.Redis@13.6.1 12 48 10 (Err() x3, ToMap() x7) 37,045 B
Aspire.Hosting.Azure.Storage@13.6.1 30 81 16 63,536 B
Aspire.Hosting (core) 260 1,609 250 1,148,073 B

The core export flags 170 experimental and 10 deprecated members. Repeating an export in a new process gives byte-identical output (SHA-256 compared). Exit codes and timings are in the Validation section.

Compared with the dump-derived reference

(owner, method) pairs that exist both in the export and in aspire.dev's current go-modules data (13.6.0), compared by exact Go signature:

Package Pairs in both Identical
Aspire.Hosting.Redis 22 22
Aspire.Hosting.Azure.Storage 36 15
Aspire.Hosting (core) 863 420

Every non-identical pair is a return-type difference (the dump-derived reference declares the capability's declared type, such as Resource, or drops a nullable pointer, where the generator returns the receiver's own interface or *string), and the export reports what the generator emits. The core export is this checkout's build, so its 41 export-only pairs are capabilities newer than 13.6.0, not drift.

Merging with the godoc PR

This change applies to main on its own and is independent of the godoc PR ("Emit godoc from ATS documentation metadata in the Go SDK generator"). Both change AtsGoCodeGenerator.cs in different places, and both add src/Shared/CodeGeneration/AtsTypeSystemCompatibility.cs with identical content plus the same link line in the Go project (the godoc PR also points the TypeScript generator at that shared file), so git merges them without conflicts.

The PR that merges second needs a two-line fix-up that git cannot detect, because the godoc change adds BuildDocumentationMaps and an includeDocs parameter to RenderGoExportedValueType:

  1. In AtsGoCodeGenerator.ApiProjection.cs, BuildApiModel: add BuildDocumentationMaps(context); directly after BuildNameMaps(context);, so documentation rendering during the projection has its maps.
  2. In ProjectExportedValues: call RenderGoExportedValueType(node, indentLevel: 0, includeDocs: false), because the call no longer compiles without the new argument.

Then re-accept GoApiExportTests.GoOnlySurface.verified.json: DTO, enum and field summaries now flow into the export. With both changes merged and the fix-up applied, the Go codegen test project passes.

Behavior notes

  • Documentation text is whatever the generator emits today. In the SDK-built AppHost server that the Debug CLI used, a restored integration's XML documentation file was not next to its assembly, so summaries are sparse for those NuGet integrations (Redis 11 of 48 members, Azure Storage 9 of 81) and fuller for Aspire.Hosting, a project reference (1,068 of 1,609).
  • The scanner reads the layout of the generator's own output. The parity tests fail if that layout changes in a way the scanner cannot read.
  • Names are reserved across all types in the context (the exported package plus Aspire.Hosting), as in generation. An app that combines many integrations can get a different disambiguation suffix where two packages collide.
  • The export is a pure function of the ATS context: no new process launches, file IO or network calls. The core export is about 1.1 MB.
  • The CLI writes the document to stdout followed by a platform newline.

Tests

  • GoApiExportTests (28 cases, three Verify snapshots) projects a test AppHost through the real generator and checks parity in both directions: every type, function, interface member and variable the generator emits is in the export, and nothing is exported that the generator does not emit. It also covers the Go-only members, trailing options flattening, callbacks and unions, augmenting packages, unique ids, determinism, LF line endings, cancellation and the scanner.
  • ApiReferenceExportTests and CodeGenerationResolverTests (RemoteHost) resolve and run the Go exporter through CodeGenerationService. The existing "language without an exporter" test uses Python instead of Go, since Go ships an exporter.
  • SdkExportCommandTests (CLI) checks that sdk export --language go resolves the Go generator when the feature is enabled.

Follow-ups

  1. Go export: add type and optional to DTO fields and constants (from AtsDtoPropertyInfo.IsOptional). Today the type is only inside the member declaration, and every DTO field carries omitempty.
  2. aspire.dev: build the Go API reference from aspire sdk export -l go, which removes the return-type and nullable differences above.
  3. Copy XML documentation next to restored integration assemblies in the SDK-built AppHost, so NuGet integrations get summaries.
  4. Go export: optional grouped functions and appliesTo view. The dump-derived reference lists one signature per capability, while the export repeats a member per concrete interface.

Validation

Command Exit Result
.\restore.cmd 0 passed
dotnet test --project tests/Aspire.Hosting.CodeGeneration.Go.Tests/Aspire.Hosting.CodeGeneration.Go.Tests.csproj --no-launch-profile -- --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" 0 61 total, 61 passed, 0 failed, 0 skipped (28 are new)
dotnet test --project tests/Aspire.Hosting.RemoteHost.Tests/Aspire.Hosting.RemoteHost.Tests.csproj --no-launch-profile -- --filter-class "*.ApiReferenceExportTests" --filter-class "*.CodeGenerationResolverTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" 0 21 total, 21 passed, 0 failed, 0 skipped
dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.SdkExportCommandTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" 0 31 total, 31 passed, 0 failed, 0 skipped
dotnet run --project tools/SelectTests -- --from upstream/main --to HEAD --explain 0 16 changed files, 0 unattributed, 4 of 99 test projects selected
aspire sdk export --language go --package Aspire.Hosting.Redis@13.6.1 0 37,045 B in 21.3 s (includes building the AppHost server)
aspire sdk export --language go --package Aspire.Hosting.Azure.Storage@13.6.1 0 63,536 B in 8.0 s
aspire sdk export --language go 0 1,148,073 B in 7.8 s

upstream is the microsoft/aspire remote. The three exports ran in a directory whose aspire.config.json contains {"features":{"experimentalPolyglotGo":true}}, with DOTNET_ROOT pointing at this checkout's .dotnet and ASPIRE_CLI_TELEMETRY_OPTOUT=1. Stdout is the JSON document only. Times are wall clock on a developer machine.

The new Verify snapshots (GoApiExportTests.FocusedApiExport, GoOnlySurface and AugmentingPackage) were reviewed before they were accepted.

Conditional test selection: the selector selects Aspire.Cli.EndToEnd.Tests, Aspire.Cli.Tests, Aspire.Hosting.CodeGeneration.Go.Tests and Aspire.Hosting.RemoteHost.Tests and triggers cli-starter-validation, extension-e2e, polyglot and typescript-api-compat. The new files live in projects the trigger map already covers, and the linked shared file is attributed by the project graph, so eng/github-ci/test-trigger-map.yml needs no change.

Not verified:

  • The full Aspire.Cli.Tests and Aspire.Hosting.RemoteHost.Tests suites. Only the classes above ran. The TypeScript exporter and the other languages' generators are not touched and were not run.
  • A release or native AOT build of the CLI. The exports above use a Debug CLI, and the only CLI change is a help string.
  • aspire sdk export --language go with experimentalPolyglotGo off was not run. Reading the code, language discovery does not list Go in that case (DefaultLanguageDiscovery), so the CLI does not add the Go generator package and the AppHost server answers No code generator found for language: go. Available languages: ..., which does not name the feature. The other experimental languages behave the same way, and the message goes away when the feature flag is removed ([Go AppHost preview] Remove the feature flag and expose Go templates #21106).
  • The bundle (prebuilt AppHost) flow and integrations referenced as local projects. Summary coverage there is not measured.
  • Apps that combine many integrations. Names are compared only for the exported package plus Aspire.Hosting.
  • The polyglot validation job and the rest of the CI matrix. CI is the first run there.
  • The combination with the godoc PR beyond the Go codegen test project, which passed on a throwaway merge. No end-to-end export was run on the merged tree.

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

Project the Go surface through the same code paths as AtsGoCodeGenerator so
the exported API reference cannot drift from the generated SDK: handle
interfaces, options structs, DTOs, enums, exported values, the CreateBuilder
entry point, and the Go-only surface (Build(), InteractionInputCollection
helpers, Err() on every handle, ToMap() on options and DTOs, and the
hand-written base runtime types).

The exporter is a separate type from the code generator because
Aspire.TypeSystem is force-shared with a frozen AssemblyVersion; newer
Aspire.TypeSystem members are probed rather than referenced directly.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Cover the Go export with Verify snapshots of the serialized document
(focused handle/DTO/enum surface, the Go-only surface, and an augmenting
package), parity checks between the identifiers the generator emits and the
identifiers in the export, determinism, LF-only output, ownership scoping,
the declaration scanner, and the exporter contract. RemoteHost tests cover the
Go RPC export and resolver lookup; Python is now the language without an
exporter.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Mention Go in the `--language` help text and describe the Go export items and
Go-only surface in the CLI output spec. A CLI test verifies that
`aspire sdk export --language go` resolves the Go generator when the Go
feature is enabled.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Move AtsTypeSystemCompatibility into src/Shared/CodeGeneration and link it into the Go generator project, so polyglot generators read the additive AtsCapabilityInfo.IsExperimental member through one probe instead of a copy per generator.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Exported declarations carry no comments because documentation is exported as member summaries. Compare them with the comment lines of the generated aspire.go removed so the check does not depend on whether the generator documents fields inside an exported value.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
@github-actions

Copy link
Copy Markdown
Contributor

🚀 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 -- 21195

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21195"

@github-actions github-actions Bot added the area-integrations Issues pertaining to Aspire Integrations packages label Oct 20, 2026
@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot October 20, 2026 07:01
@github-actions

This comment has been minimized.

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.

🟡 Changes recommended

The declaration scanner silently omits valid Go identifiers beginning with non-ASCII uppercase letters.

1 open issue
What changed in this PR

Adds canonical Go API reference export to aspire sdk export, using the Go SDK generator rather than independently reconstructing signatures.

Changes:

  • Adds Go API projection, declaration scanning, and deterministic JSON serialization.
  • Preserves generator compatibility with older CLI contracts.
  • Adds export tests, snapshots, and CLI documentation.
File Description
tests/​Aspire.Hosting.RemoteHost.Tests/​CodeGenerationResolverTests.cs Tests Go exporter discovery.
tests/​Aspire.Hosting.RemoteHost.Tests/​CodeGeneration/​ApiReferenceExportTests.cs Tests Go export schema and ownership.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​GoApiExportTests.GoOnlySurface.verified.json Captures Go-specific API surface.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​GoApiExportTests.FocusedApiExport.verified.json Captures canonical JSON serialization.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​GoApiExportTests.AugmentingPackage.verified.json Captures package augmentations.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​GoApiExportTests.cs Tests projection, parity, determinism, and scanning.
tests/​Aspire.Cli.Tests/​Commands/​Sdk/​SdkExportCommandTests.cs Tests feature-enabled Go resolution.
src/​Shared/​CodeGeneration/​AtsTypeSystemCompatibility.cs Adds optional contract-member probing.
src/​Aspire.Hosting.CodeGeneration.Go/​GoDeclarationScanner.cs Scans generated and runtime Go declarations.
src/​Aspire.Hosting.CodeGeneration.Go/​GoApiModel.cs Defines the export model.
src/​Aspire.Hosting.CodeGeneration.Go/​GoApiExportWriter.cs Serializes canonical JSON.
src/​Aspire.Hosting.CodeGeneration.Go/​AtsGoCodeGenerator.cs Makes the generator partial.
src/​Aspire.Hosting.CodeGeneration.Go/​AtsGoCodeGenerator.ApiProjection.cs Projects generator output into reference data.
src/​Aspire.Hosting.CodeGeneration.Go/​AtsGoApiReferenceExporter.cs Implements the Go exporter.
src/​Aspire.Hosting.CodeGeneration.Go/​Aspire.Hosting.CodeGeneration.Go.csproj Links the compatibility helper.
src/​Aspire.Cli/​Commands/​Sdk/​SdkExportCommand.cs Adds Go to language help.
docs/​specs/​cli-output-formats.md Documents Go export support.

Review effort: Balanced

Go exports every identifier whose first character is a Unicode upper
case letter, and the generator's naming helpers (char.IsUpper,
char.ToUpperInvariant) can produce non-ASCII names. The scanner only
treated ASCII upper case letters as exported, so such declarations were
missing from the API export. Identifier tokenization splits on
delimiters, so only the exported check needed to change.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

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.

🔵 Needs a closer look

The substantial declaration scanner, cross-package projection, and cross-version loading behavior warrant final human validation.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@github-actions

This comment has been minimized.

@github-actions

Copy link
Copy Markdown
Contributor

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

…porter

Resolve the SdkExportCommandTests conflict: main moved workspace ownership into the test callers (TemporaryWorkspace is now passed in rather than returned via out), so the Go feature-flag test and the new IFeatures parameter are adapted to that CreateProvider shape.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot October 27, 2026 11:51
- Add a parity test that exports the test-types package through
  AtsContextFilter.FilterForApiExport, as CodeGenerationService does, and
  checks its Go names and member declarations against a full generation.
  RemoteHost internals become visible to the Go codegen tests for it.
- Replace the Assert.DoesNotContain checks in the Go and TypeScript export
  tests with positive assertions.
- Add GoDeclarationScanner.ScanRuntime, which throws on an exported construct
  the scanner does not model, and use it for the hand-written runtime scan so
  such a construct fails the export instead of going missing from it.

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

Copy link
Copy Markdown
Member Author

Interaction with #21197: it adds BuildDocumentationMaps(context) next to BuildNameMaps in GenerateAspireSdk and initializes _docs there, not inside BuildNameMaps. Whichever PR lands second needs BuildApiModel to call BuildDocumentationMaps as well. ...

No change here. Whichever of the two PRs lands second adds the BuildDocumentationMaps(context) call in BuildApiModel.

Interaction with #21183: it removes KnownFeatures.ExperimentalPolyglotGo, so the new CLI test here stops compiling once both land. ...

No change here. #21183 lands last, so it drops the feature-flag setup, renames the CLI test and updates the doc sentence.

There is no CLI end-to-end coverage for aspire sdk export --language go. ... If you add one, please check the test-trigger map, since it would add a runtime-only package dependency.

Not added in this PR. It can only be validated in CI, and eng/github-ci/test-trigger-map.yml has no Aspire.Hosting.CodeGeneration.Go entry yet (only the Aspire.Hosting.CodeGeneration.* wildcard), so it belongs with the CLI end-to-end coverage tracked in #21108.

Minor: GoApiExportTests.cs:251 and the new ExportApi_Go_ReturnsCanonicalSchemaForRequestedPackage use Assert.DoesNotContain, which the repo guidelines discourage in favor of asserting what is present.

Done in da2ae47: the two Assert.DoesNotContain uses in GoApiExportTests and the two in ApiReferenceExportTests (TypeScript and Go) now assert what is present instead.

@github-actions

This comment has been minimized.

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.

🔵 Needs a closer look

Human assessment is needed because a critical finding omitted from the published review identifies invalid Go field declarations for nested configuration values.

No open issues 🎉

Review effort: Balanced

…exporter

No conflicts. Main now emits the Any<Type> accepting interfaces and their marker methods, which the Go API export does not project yet; that follows in the next commit.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The Go generator emits an Any<Type> interface for every handle type that
another handle type derives from, and declares the unexported marker
methods (isContainerResource and so on) on the handle interfaces. The API
export projected neither, so it omitted names and methods that the
generated SDK declares.

Project each Any<Type> interface as an interface item owned by the package
that owns its base type. A package that does not own the base type gets an
opaque stub, like it does for a handle interface. List a handle
interface's accepting markers first, in the order the generator writes
them, and note in the output format spec that the Any<Type> set depends on
the exported package set, like the other Go names.

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

No conflicts. The incoming change (#21278) only touches the Entra ID integration and its tests.

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

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.

🟡 Changes recommended

The exported union types incorrectly exclude supported derived builders because they use return-type mapping rather than the input types used by the generated guard.

1 open issue

Review effort: Balanced

@github-actions

This comment has been minimized.

The Go API export mapped union members as return types, so a union that
holds a base handle type (WithPoolOrName(pool any) taking a PoolResource
or a string) listed PoolResource. The generator maps the same members as
inputs and emits the Any<Type> accepting interface for a handle that has
derived types, so the guard and godoc say AnyPoolResource, string and the
reference disagreed with them.

Use the generator's GetUnionMemberTypes so allowedTypes cannot drift from
the emitted guard, and add a regression test on the derived-builder
fixture that compares the export with the generated switch case.

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

Copy link
Copy Markdown
Contributor

Tests selector

9 / 100 PR test projects · 4 PR jobs, from 18 changed files.

Selected PR test projects (9 / 100)

Aspire.Cli.EndToEnd.Tests, Aspire.Cli.Tests, Aspire.Hosting.CodeGeneration.Go.Tests, Aspire.Hosting.CodeGeneration.Java.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.Rust.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.RemoteHost.Tests, Aspire.Managed.Tests

Selected PR jobs (4)

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


How these were chosen — grouped by what changed

🔧 src/Aspire.Hosting.RemoteHost/Aspire.Hosting.RemoteHost.csproj (changed source)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests
→ 5 via the project graph: Aspire.Hosting.CodeGeneration.Java.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.Rust.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Managed.Tests (2 hops)

🔧 src/Aspire.Hosting.CodeGeneration.Go/AtsGoCodeGenerator.cs (changed source)
→ 2 directly: Aspire.Cli.Tests, Aspire.Hosting.CodeGeneration.Go.Tests

📦 affected project Aspire.Cli
→ 1 test: Aspire.Cli.EndToEnd.Tests

🔧 src/Aspire.Hosting.CodeGeneration.Go/Aspire.Hosting.CodeGeneration.Go.csproj (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🔧 src/Aspire.Hosting.CodeGeneration.Go/AtsGoApiReferenceExporter.cs (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🔧 src/Aspire.Hosting.CodeGeneration.Go/AtsGoCodeGenerator.ApiProjection.cs (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🔧 src/Aspire.Hosting.CodeGeneration.Go/GoApiExportWriter.cs (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🔧 src/Aspire.Hosting.CodeGeneration.Go/GoApiModel.cs (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🔧 src/Aspire.Hosting.CodeGeneration.Go/GoDeclarationScanner.cs (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Cli.Tests/Commands/Sdk/SdkExportCommandTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/AtsGoDerivedBuilderTests.cs (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/GoApiExportTests.cs (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/GoApiExportTests.AugmentingPackage.verified.json (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/GoApiExportTests.FocusedApiExport.verified.json (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/GoApiExportTests.GoOnlySurface.verified.json (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/CodeGeneration/ApiReferenceExportTests.cs (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

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

Job reasons

Job Triggered by
cli-starter-validation affected project Aspire.Cli
extension-e2e • src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs, src/Aspire.Hosting.RemoteHost/Aspire.Hosting.RemoteHost.csproj
• affected project Aspire.Cli
polyglot affected project Aspire.Cli
typescript-api-compat affected project Aspire.Cli

Selection computed for commit dec9cd9.

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.

🔵 Needs a closer look

Human assessment is needed to evaluate the impact of exported union-type metadata omitting numeric types that generated methods accept.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

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.

Thanks for the quick turnaround. Everything I raised is now either addressed or answered with a clear rationale:

  • Names relative to the exported package set: the spec and the exporter comment now document the caveat, including how options structs and Any<Type> interfaces behave. ApiExport_ThroughTheExportFilter_NamesPackageMembersAsFullGenerationDoes covers the production FilterForApiExport path against a full generation. This was my blocker, and it is resolved.
  • Options ownership: documented per package under its own typeId, and covered by the filtered parity test.
  • Runtime scan drift: GoDeclarationScanner.ScanRuntime now fails on exported constructs it does not model, including exported interfaces with bodies.
  • ExperimentalPolyglotGo test vs #21183: understood. Whichever PR lands second will drop the feature setup.

The new commits also look good. The Any<Type> accepting interfaces are now exported, and union allowedTypes now come from GetUnionMemberTypes, so they match the emitted guard. The Go codegen tests pass on this head.

Approving. One non-blocking follow-up: a CLI end-to-end test for aspire sdk export --language go (alongside the TypeScript one in SdkExportTests) would still be a nice addition later.

@IEvangelist
David Pine (IEvangelist) merged commit 769cf38 into main Oct 30, 2026
223 checks passed
@microsoft-github-policy-service microsoft-github-policy-service Bot added this to the 17.0 milestone Oct 30, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Pull request created: #1980

Generated by PR Documentation Check · copilot · auto · 29.5 AIC · ⌖ 1.13 AIC · ⊞ 7.1K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

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

Added a "Export Go API reference data" entry to the Aspire 17.0 what's-new page. Triggered signals: cli_command_file_changed (SdkExportCommand.cs now lists go), polyglot_code_generator_changed (new Go exporter), pr_body_has_cli_flag_mention (aspire sdk export --language go), pr_body_has_deprecation_marker.

Note

This draft PR needs human review before merging.

David Pine (IEvangelist) added a commit that referenced this pull request Oct 30, 2026
…21197)

> [!NOTE]
> **Merge order:** no PR must land before this one. #21188 and #21199,
which overlapped it, are on main and this branch contains them.
Whichever of the remaining open PRs lands second rebases:
>
> - A PR that changes `TwoPassScanningGeneratedAspire.verified.go` (a
new or changed `Aspire.Hosting` API reaches it) conflicts with this one
there, because this PR adds doc comments throughout the file. Regenerate
the snapshot with `dotnet verify accept -y` instead of merging hunks by
hand. `AtsGeneratedAspire.verified.go` works the same way.
> - #21195 calls `RenderGoExportedValueType`, whose signature this PR
changes, so the second to land needs a one-line fix-up in
`AtsGoCodeGenerator.ApiProjection.cs`.

## Description

Part of #21115.

The Go SDK generator documents a member only from the capability
`Description`, plus a few fixed comments for enums, DTOs and handles.
`Summary`, `Remarks`, `Returns`, per-parameter docs, enum value docs and
the obsolete and experimental flags never reach `aspire.go`, so `go doc`
and gopls hover show one thin line or nothing. This PR emits godoc from
the same ATS documentation metadata the TypeScript generator already
turns into JSDoc.

### What changes in the generated SDK

Documentation flows to every kind of declaration:

- Capabilities (handle methods, standalone functions, property getters
and setters): summary, remarks, a `Parameters:` list and a `Returns:`
paragraph. A trailing `...Options` parameter points at its Options
struct, and each Options field carries the doc of its parameter.
- Handle interfaces, DTO structs and their fields, enum types and each
enum value, exported value groups and their members, and Options
structs.

The comments follow godoc conventions:

- A comment starts with the identifier it documents, paragraphs are
separated by a bare `//`, and code samples and lists from the XML docs
keep an indented-block form. Lines are wrapped near 80 columns and never
split a word.
- `<see cref>` references become `[Name]` doc links only for generated
types. Anything else stays plain text so the SDK has no dangling links.
- Obsolete capabilities end with a `Deprecated:` paragraph, the one
marker gopls and staticcheck recognize.
- Experimental capabilities get a `# Experimental` heading and the line
`Notice: This API is EXPERIMENTAL and may be changed or removed in a
later release.` Go has no toolchain-recognized experimental marker, so
this uses the convention `google.golang.org/grpc` documents its
experimental APIs with. It renders as a heading on pkg.go.dev and in
gopls hover and is stable under gofmt. TypeScript uses `@experimental`.
- XML-doc text is normalized to LF and no comment line has trailing
whitespace.
- A one-line remarks paragraph that gofmt and `go doc` would read as a
heading, such as `Requires Redis 7.2` or `Used with the resource's
name`, ends with a period so it stays a paragraph.

Example from the test snapshot. On main this method has only the first
line:

```go
// WithPreviewStatus sets the preview status.
//
// Parameters:
//   - status: The status to set.
//
// # Experimental
//
// Notice: This API is EXPERIMENTAL and may be changed or removed in a later
// release.
//
// Deprecated: Use WithDocumentation instead.
WithPreviewStatus(status DocumentedStatus) DocumentedResource
```

### Commits

1. **Share the ATS version-skew probe between polyglot generators.**
`AtsTypeSystemCompatibility` (reads the experimental flag from an
`Aspire.TypeSystem` that may predate it) moves from the TypeScript
generator project to `src/Shared/CodeGeneration` and is linked into the
Go and TypeScript generator projects. The TypeScript generator only
gains a `using`.
2. **Emit godoc from ATS documentation metadata in the Go SDK
generator.** New `GoDocComment.cs` formats a comment from the metadata,
and `AtsGoCodeGenerator.cs` calls it at each declaration.
3. **Escape ATS metadata at the Go generator output sinks.** Injection
hardening, described below.
4. **Render exported string values as Go string literals.** The same
sink class for exported values, described below.
5. **End one-line remarks that gofmt would turn into headings with a
period.** See the conventions list above.
6. **Make the escaping and gofmt round-trip comments state what they
cover.** Comments only.
7. **Build the Go doc maps with the name maps.** `BuildNameMaps` builds
the documentation maps itself, so a caller that builds only the name
maps still gets a usable renderer (review feedback).

### Escape ATS metadata at the Go generator output sinks

ATS metadata (descriptions, capability ids, parameter and property
names) was spliced into Go source unescaped. A multi-line description,
or a name containing a quote, a newline or a percent sign, produced Go
that did not compile or that carried extra statements. Now:

- every doc comment line is prefixed with `//`: CR, LF and CRLF start a
new comment line, and Unicode line and paragraph separators, control
characters and the byte order mark are replaced or dropped, so a
description cannot end the comment;
- string literals (capability ids, request argument names, json struct
tags, map keys, enum constant values and `%q` arguments) go through one
`GoStringLiteral` helper, and a capability id inside a `fmt.Errorf`
format string has its `%` doubled;
- method names (`ToPascalCase`) go through the existing
`SanitizeIdentifier`, as parameter and type names already did;
- exported string values, enum values and dictionary keys go through
`GoStringLiteral` too (see the review finding below).

This is a low-severity robustness fix. An integration author already
runs code on the developer's machine, so no trust boundary is crossed.
Output for valid first-party names is unchanged: the hardening commits
change no snapshot that exists on main. The shared scanner and the other
language generators have the same pattern and are left for a follow-up.

A review of this change found one more sink of the same class, rated
Medium and fixed by commit 4. Exported string values, enum values and
dictionary keys were written with the relaxed JSON writer, which spells
a character outside the Basic Multilingual Plane (for example an emoji)
as a UTF-16 surrogate pair such as `\uD83D\uDE00`. Go rejects surrogate
halves in a string literal, so one such value failed `go build` for the
whole SDK with `escape is invalid Unicode code point U+D83D`. These
values now go through `GoStringLiteral`, which keeps such characters as
UTF-8. Numbers and booleans are the same text in JSON and Go and render
as before.

### Generated output and cost

- Two-pass SDK (`aspire.go` for `Aspire.Hosting` plus the test types):
1,347,950 to 1,808,456 bytes (+34.2%) and 31,892 to 45,393 lines. The
smaller test-types snapshot: 162,529 to 176,209 bytes (+8.4%) and 4,591
to 5,049 lines.
- The sequence of non-comment, non-blank lines in both large snapshots
is identical to main (27,526 and 3,730 lines compared, 0 differences).
The snapshot diffs are doc comment lines and the blank lines that
separate them.
- Markers in the two-pass snapshot: `Deprecated:` 16, `# Experimental`
221, `Parameters:` 848, `Returns:` 789.
- Generation time, scan excluded, 1 warm-up and 15 samples on a shared
developer machine: median 16.0 ms on main and 104.2 ms with this change
(+88 ms), min 12.8 ms and 85.7 ms. This was measured before main's
latest Go generator changes were merged and not repeated. The cost is
linear in the number of documented identifiers and the regular
expressions are source-generated. It was not profiled further.

Review tip: read `DocumentedMetadataGeneratedAspire.verified.go`,
`EscapedMetadataGeneratedAspire.verified.go` and
`GoDocCommentRender.verified.txt` first. The two large snapshot diffs
are comments only.

### Tests and guard

New tests are in `GoDocCommentTests.cs` and
`GoGeneratorEscapingTests.cs`. They build their metadata in code, so the
TypeScript `TestTypes` that the Go, Java, Python and Rust test projects
link are untouched.

- `GenerateDistributedApplication_WithDocumentedMetadata_EmitsGodoc`
(Verify snapshot) covers every declaration kind above, including
`Deprecated:`, `# Experimental`, enum values, special characters and
CRLF input.
- `Render_FormatsGodocBlocks` (Verify snapshot) covers the comment
formatter, and `Render_KeepsEveryLineInsideTheComment` proves hostile
text never leaves the `//` comment.
`Render_EndsHeadingLookingRemarksWithAPeriod` proves that one-line
remarks which `go/doc/comment` would read as a heading (gofmt rewrites
them to `# Heading`) end with a period.
- `GeneratedSdk_DocCommentsFollowGodocConventions` is the guard that
documented APIs keep their docs: over the SDK generated from the real
scanned `Aspire.Hosting` assembly, every commented declaration starts
with its name, no line has trailing whitespace or a lone CR,
`Deprecated:` starts its own paragraph, obsolete and experimental
metadata present in the model reaches the output, and the documented
enum values equal the commented constants. The two-pass snapshot also
covers the whole SDK, so an XML-doc edit to a scanned `Aspire.Hosting`
API changes it, the same coupling the TypeScript snapshot has.
- `GeneratedSdk_PassesGoToolchainChecks` runs `go build ./...`, `go vet
./...` and `gofmt` on that SDK and asserts gofmt leaves the generated
top-level doc comments unchanged. go/printer only reformats doc comments
that start in column 1, so the indented interface-method and
struct-field comments are covered by the heading test above instead.
- `GoGeneratorEscapingTests` generates an SDK from hostile metadata: a
description of `Adds Foo.\nfunc init() {}\n// ` that tries to end the
comment and declare a function, capability ids, method, parameter and
property names containing double quotes, percent signs, backslashes,
hyphens and line separators, and exported values (a string, an enum
value and a dictionary key) containing an emoji. It checks the Verify
snapshot, that no injected statement appears in the output, and that the
output passes `go build` and `go vet`. With the escaping commit's
generator changes reverted, all three fail (the injected statement is in
the output, the snapshot differs and `go build` reports syntax errors).
With only the exported-value rendering reverted, the snapshot differs
and `go build` reports `escape is invalid Unicode code point U+D83D`.

The Go toolchain tests use the existing `[RequiresTools]` gate, like
`GeneratedTransport_SupportsDuplexCommunication`, so this PR adds no
test project, CI job or runtime dependency.
`eng/github-ci/test-trigger-map.yml` needs no entry: the moved file is a
linked `src/Shared` file, which the selector attributes to its consuming
projects, and the Python, Java and Rust generators and tests do not
reference it (see the `SelectTests` row below).

### Merging with the Go API reference exporter

#21195 adds the Go API reference exporter to the same project. At its
current head (`ec5022d3a9`) the two pull requests merge without textual
conflicts (checked with `git merge-tree`), but the exporter calls
`RenderGoExportedValueType`, which this change gives a required
`includeDocs` parameter, so whichever merges second needs a one-line
fix-up in `AtsGoCodeGenerator.ApiProjection.cs`: in
`ProjectExportedValues`, pass `includeDocs: false` to
`RenderGoExportedValueType`. The compiler flags that call.

`BuildNameMaps` builds the documentation maps itself, so the exporter's
`BuildApiModel` can render documentation without any change.

The exporter's `GoApiExportTests.GoOnlySurface` snapshot then shows the
ATS documentation summaries in place of the generated `X represents X.`
text. A trial merge of both heads with that fix-up built, and 80 of the
81 tests in the Go codegen test project passed. The one failure was that
snapshot, which differed only in those summaries and is re-accepted with
`dotnet verify accept -y`. That trial ran at earlier heads of both
branches (see Not verified).

### Merge with main

This branch merges main (`45de07f9e3`), which now contains #21188,
#21199 and #21261. The conflicts were in `AtsGoCodeGenerator.cs` and two
snapshots, and the resolution keeps both sides:

- Both sets of private fields and helpers are kept. `BuildNameMaps`
builds the accepting interfaces from #21199 first and the documentation
maps last, because the renderer resolves type names through the maps
built before it.
- The enum value constant takes its name from
`GetEnumMemberConstantName` (#21199), with this PR's value doc block and
string-literal escaping.
- DTO callback conversion keeps this PR's escaped map key together with
the updated `EmitGoCallbackShimBody` call from #21261.
- The union allowed-types note now also says that `float64` accepts any
built-in Go numeric type, matching the widened type switch from #21188.

The snapshots were regenerated, not merged by hand. In the two large
ones the non-comment, non-blank lines are identical to main's (see the
counts above).

## Validation

Run from the repository root on Windows after `restore.cmd`, with Go
1.27.0 installed so the `[RequiresTools]` tests ran and were not
skipped.

| Command | Exit | Result |
| --- | --- | --- |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.Go.Tests\Aspire.Hosting.CodeGeneration.Go.Tests.csproj
--no-launch-profile -- --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` | 0 | 79 passed, 0 failed, 0
skipped (65 on main) |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.TypeScript.Tests\Aspire.Hosting.CodeGeneration.TypeScript.Tests.csproj
--no-launch-profile -- --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` | 0 | 153 passed, 0 failed, 0
skipped (153 on main) |
| `dotnet run --project tools/SelectTests -- --from upstream/main --to
HEAD --explain` | 0 | 0 unattributed changed files, no fallback. Selects
7 of 100 PR test projects: `Aspire.Cli.EndToEnd.Tests`,
`Aspire.Cli.Tests`, `Aspire.Hosting.CodeGeneration.Go.Tests`,
`Aspire.Hosting.CodeGeneration.TypeScript.Tests`,
`Aspire.Hosting.Native.Core.Tests`, `Aspire.Hosting.RemoteHost.Tests`,
`Aspire.Managed.Tests`, and triggers the `cli-starter-validation`,
`extension-e2e`, `homebrew-installer`, `polyglot`,
`typescript-api-compat`, `typescript-sdk` and `winget-installer` PR
jobs. The Python, Java and Rust codegen test projects are not selected.
|

Not verified:

- The `polyglot` job and the full CI matrix. Of the selected test
projects, only the Go and TypeScript codegen projects and the code
generation classes of `Aspire.Hosting.RemoteHost.Tests`
(`CodeGenerationResolverTests`, `ApiReferenceExportTests` and
`ServiceErrorMessageTests`, 22 tests) were run locally. CI is the first
run for the rest.
- Whether the CI runners that run the Go test project have `go` on
`PATH`. The three toolchain tests depend on `[RequiresTools]`.
- That the generated SDK body is gofmt-clean. It is not clean on main
either, so only the comments are gofmt-checked.
- Generation time was measured once on a shared, busy machine, with main
and this change measured at different times.
- The checks that the new tests fail without each fix were run before
the two merges of main into this branch (`f06f16b7bf` and `45de07f9e3`)
and were not repeated.
- The Python, Java and Rust codegen test projects (29, 71 and 26 tests)
passed on an earlier head of this branch and were not re-run after the
exported-value and heading fixes. They do not link the moved shared file
or any file those fixes changed.
- The merge with #21195 was built and tested locally at its head
`7e3948ad85` and an earlier head of this branch only, in the Go codegen
test project and not in the full CI matrix. At its current head
`ec5022d3a9` only the textual merge was checked. #21195 may change
before it lands.

### Follow-up issues

- Escape ATS metadata in the shared scanner and the TypeScript, Python,
Java and Rust generators.
- Go SDK: package doc, standard generated-code header, gofmt-clean body,
LF output.
- Scanner: preserve `<para>` boundaries and code indentation.
- Go SDK: guard names derived with `ToCamelCase` (implementation names,
list and dictionary getter fields, builder and application
implementations) against Go keywords, and make `ReserveName` reject
keywords and predeclared names.

## Checklist

- Is this feature complete?
  - [ ] Yes. Ready to ship.
  - [x] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
  - [x] 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
  - [x] 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
  - [x] No

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Karol Zadora-Przylecki (karolz-ms) pushed a commit that referenced this pull request Oct 30, 2026
#21432)

## Description

Fixes an untracked intermittent Windows CI failure in
`Aspire.Hosting.Java.Tests.AddJavaContainerTests.AddJavaContainer_ExportsTelemetryToAspire`:

```
Expected: "http://:4317"
Actual:   "http://"
   at AddJavaContainerTests.cs:124
```

### Root cause

`DcpDependencyCheck.GetDcpInfoAsync` runs `dcp info`. When the container
runtime CLI is slow or hangs (common on loaded Windows runners), DCP
hits its internal ~10s deadline and still returns JSON, but with
`"runtime":""` and `"hostName":""` (error: `context deadline exceeded`).
`DcpContainersInfo.ContainerHostName` was `HostName ?? <runtime
default>`, so the empty string bypassed the fallback. `HostUrl` then set
`uri.Host = ""`, so the container got an `OTEL_EXPORTER_OTLP_ENDPOINT`
with no host. Each failing test took about 10s, which matches DCP's
internal timeout. The test computes its expected value from the same
`ContainerHostName`, which is why CI shows "expected" `http://:4317`.

This is a product bug, not just a test bug. Under the same conditions, a
real app would give containers an unusable OTLP endpoint.

### Fix

- `DcpContainersInfo.ContainerHostName`: treat an empty or null
`HostName` as missing and fall back to the runtime default
(`host.docker.internal` / `host.containers.internal`).
- `DcpExecutor.ContainerHostName` and
`ContainerNetworkEndpointProvisioner.GetContainerHostNameAsync` read the
raw `HostName` directly. They now use `ContainerHostName`, so all
consumers agree.

No assertions were weakened, and no sleeps or retries were added.

### Evidence

Main `ci.yml` first attempts from 2026-10-23 to 2026-10-30 (63 runs, all
attempt 1; no reruns): `Hosting.Java (windows-latest)` failed in **4**
jobs with the identical assertion. `Hosting.Java (ubuntu-latest)` had no
failures. Denominator: 51 of the 63 runs reached the Hosting.Java jobs
(the other 12 were cancelled). On Windows, 4 of 51 first-attempt jobs
failed with this assertion. 3 more failed only because the hosted runner
lost communication (#20165), and 44 passed. On Ubuntu, 0 of 51 failed.
-
https://github.com/microsoft/aspire/actions/runs/40248143715/job/121334626038
-
https://github.com/microsoft/aspire/actions/runs/40279576972/job/121430279380
-
https://github.com/microsoft/aspire/actions/runs/40554609235/job/122368459861
-
https://github.com/microsoft/aspire/actions/runs/40914588301/job/123603952054
(2026-10-29, after the last test change, #21254)

**Native repro (Linux, DCP 0.27.2):** with a `docker` shim on `PATH`
that runs `sleep 600`, `dcp info` returns after 10.04s with
`"runtime":"","hostName":""`. A healthy docker returns
`"hostName":"host.docker.internal"`. Feeding that JSON through the old
logic produced `OTEL_EXPORTER_OTLP_ENDPOINT='http:'`. With the fix it
produced `http://host.docker.internal:4317`.

**Regression tests (Aspire.Hosting.Tests):**
-
`DcpDependencyCheckTests.ContainerHostName_FallsBackWhenDcpReportsNoHostName`
deserializes real DCP JSON. It covers the timeout output, podman with an
empty hostName, a missing hostName, and a custom hostName.
-
`ExpressionResolverTests.HostUrlInOtlpExporterEndpointUsesFallbackHostWhenDcpReportsEmptyHostName`.
- Before the fix (src stashed): 2 `DcpDependencyCheckTests` cases fail
with `""`, and the ExpressionResolver test fails with `http://`, the
exact CI symptom.
- After the fix: `DcpDependencyCheckTests` 9/9 and
`ExpressionResolverTests` 50/50 pass.

### Notes

- I didn't reproduce this on a Windows runner. Windows behavior is
inferred from the identical symptom, the ~10s duration, and DCP's
verified behavior on Linux.
- `main` currently fails to compile (CS7036 `includeDocs` at
`AtsGoCodeGenerator.ApiProjection.cs:419`, a #21195/#21197 conflict that
another fix owns). Until that lands, CI on this PR may fail for that
reason, which is unrelated to this change.

## Checklist

- Is this feature complete?
  - [x] Yes. Ready to ship.
  - [ ] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
  - [x] Yes
  - [ ] No
- Did you add public API?
  - [ ] Yes
  - [x] No
- Does the change make any security assumptions or guarantees?
  - [ ] Yes
  - [x] No

**🤖 Posted by AspireAgent (AI Agent)**

---------

Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist) added a commit that referenced this pull request Nov 5, 2026
> [!IMPORTANT]
> **Merge last.** This PR depends on the other open Go AppHost PRs and
must land after them.
>
> - **Must land first**, because each adds references to the flag that
this PR has to delete: #21189 (E2E helper and call sites), #21195
(`SdkExportCommandTests`) and #21196 (`GoAppHostToolingCheck` and its
tests).
> - **Must land first**, because it edits the same hunk of
`DefaultLanguageDiscovery.cs` and this PR rebases onto it: #21191.
> - **Should land first**, because removing the flag turns Go on for
everyone and these fixes should ship before it: #21186, #21187, #21188,
#21193, #21194, #21197 and #21199.

## Description

Removes the `experimentalPolyglotGo` feature flag so Go AppHosts are
available by default, the same way TypeScript AppHosts are. With no
flag, **Empty (Go AppHost)** and **Starter App (Go API + Redis, Go
AppHost)** are offered by interactive and non-interactive `aspire new`,
and Go is offered by `aspire init` language selection and `--language
go`.

**This is the GA switch for the Go AppHost epic (#21115) and must merge
last**, after the other children have landed: #21108 (E2E, publish,
deploy), #21110 (support policy, API review, packaging), #21112 (docs
and samples) and #21114 (VS Code debugging). It was opened as a draft so
CI exercises the 52 Go fixtures without the flag. It is ready for review
now, but not for merging.

What changed:

- **CLI:** `KnownFeatures` drops the Go flag and
`DefaultLanguageDiscovery` no longer marks Go experimental.
`LanguageInfo.IsExperimental` is kept because Python, Java and Rust
still use it.
- **Leftover key:** a stale `experimentalPolyglotGo` in a user's
configuration is ignored with no warning, matching what happened to the
TypeScript flag when it was removed. `Features` only reads named keys,
and the extension schemas set `additionalProperties: false`, so VS Code
flags the stale key.
- **Extension schemas:** `aspire-config`, `aspire-global-settings` and
`aspire-settings` are regenerated with
`extension/scripts/generate-schema.js`. Only the 16-line Go block is
removed from each.
- **Fixtures and CI:** 52
`tests/PolyglotAppHosts/*/Go/aspire.config.json` files and
`.github/workflows/polyglot-validation/Dockerfile.golang` no longer set
the key.
- **Java E2E picker offsets:** Go is always listed now, so with only the
Java flag set the `aspire init` language picker is C#, TypeScript, Go,
Java, and Java needs 3 Down presses instead of 2. The first CI run on
this PR timed out waiting for `> Java` in `JavaPolyglotTests`,
`JavaCodegenValidationTests` and `JavaPolyglotApphostDirectoryTests`;
each now presses Down once more, with a comment stating the picker
order. The order comes from `DefaultLanguageDiscovery`,
`LanguageService` and `CliTemplateFactory`. TypeScript flows are
unaffected because TypeScript sorts before Go.
- **Tests:** `DefaultLanguageDiscoveryTests`, `NewCommandTests`,
`ConfigCommandTests`, `NewCommandTemplateConfigPersistenceTests` and
`InitCommandTests` now expect Go without the flag, with 6 new tests. One
of them, `GetAvailableLanguagesAsync_ListsLanguagesInPickerOrder`, pins
the picker order so a future ungated language fails a unit test before
it breaks a Docker E2E run.
- **Docs:** `docs/specs/polyglot-apphost.md`, the Go code generation
README and `playground/GoAppHost/apphost.go` no longer mention the flag.

Fixes #21106

## Validation

| Command | Result |
| --- | --- |
| `.\restore.cmd` | passed |
| `dotnet build
tests\Aspire.Cli.EndToEnd.Tests\Aspire.Cli.EndToEnd.Tests.csproj -m:2
--no-restore` | 0 warnings, 0 errors |
| `dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj
--no-launch-profile -- --filter-class "*.DefaultLanguageDiscoveryTests"
--filter-class "*.NewCommandTests" --filter-class "*.ConfigCommandTests"
--filter-class "*.NewCommandTemplateConfigPersistenceTests"
--filter-class "*.InitCommandTests" --filter-not-trait
"quarantined=true" --filter-not-trait "outerloop=true"` | 312 passed, 0
failed (run before the picker-order test was added) |
| `dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj
--no-launch-profile -- --filter-class "*.DefaultLanguageDiscoveryTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` | 39 passed, 0 failed (38 existing plus the
picker-order test) |
| `node extension\scripts\generate-schema.js` | only the Go block was
removed from each schema |
| repository-wide search for `experimentalPolyglotGo` and its variants |
0 hits |
| JSON parse of the 53 fixtures and 3 schemas | all parse, none contain
the flag |

Run in PR CI instead of locally, all passing on `0e65752d44`: the three
Java E2E tests (`JavaPolyglotTests`, `JavaCodegenValidationTests` and
`JavaPolyglotApphostDirectoryTests`; they need Docker, so CI was the
first execution of the extra Down press), `Infrastructure.Tests` and the
VS Code extension unit and E2E jobs.

Not run: the VS Code new-project flow in an extension host
(`extension/src/commands/new.ts` just runs `aspire new`).

### Before merging

- [ ] Search again for `experimentalPolyglotGo`,
`KnownFeatures.ExperimentalPolyglotGo`,
`EnableExperimentalGoSupportAsync`, `features__experimentalPolyglotGo`
and `experimentalPolyglot:go`, because open Go branches add flag setup
of their own and this PR must merge after all of them. Today that covers
#21189 (the `EnableExperimentalGoSupportAsync` helper and its call sites
in every Go scenario), #21195 (`SdkExportCommandTests` sets
`KnownFeatures.ExperimentalPolyglotGo`) and #21196
(`GoAppHostToolingCheckTests` builds its language discovery with the
flag, including a `goEnabled: false` case that stops being meaningful,
and `GoAppHostToolingCheck` has a comment that describes the flag). Each
of them stops compiling or goes stale once the flag is removed, so
delete or rewrite them here.
- [ ] Rebase onto #21191, which adds `DefaultHostingPackages =
["Aspire.Hosting.Go"]` to Go's `LanguageInfo` in the same hunk of
`DefaultLanguageDiscovery.cs` (#21045). Keep that initializer and drop
`IsExperimental: true`.
- [ ] Drop the Go experimental notes in the aspire.dev API reference and
docs at the same time.

## Checklist

- Is this feature complete?
  - [ ] Yes. Ready to ship.
  - [x] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
  - [x] 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
  - [x] 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
  - [x] No

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-integrations Issues pertaining to Aspire Integrations packages

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants