Repository navigation
Add aspire sdk export -l go (Go API reference exporter) - #21195
Conversation
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
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 21195Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21195" |
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
🟡 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
This comment has been minimized.
This comment has been minimized.
|
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>
- 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>
No change here. Whichever of the two PRs lands second adds the
No change here. #21183 lands last, so it drops the feature-flag setup, renames the CLI test and updates the doc sentence.
Not added in this PR. It can only be validated in CI, and
Done in da2ae47: the two |
This comment has been minimized.
This comment has been minimized.
…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>
This comment has been minimized.
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>
Tests selector9 / 100 PR test projects · 4 PR jobs, from 18 changed files. Selected PR test projects (9 / 100)
Selected PR jobs (4)
How these were chosen — grouped by what changed🔧 🔧 📦 affected project 🔧 🔧 🔧 🔧 🔧 🔧 🧪 🧪 🧪 🧪 🧪 🧪 🧪 🧪 Job reasons
Selection computed for commit |
Sébastien Ros (sebastienros)
left a comment
There was a problem hiding this comment.
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_NamesPackageMembersAsFullGenerationDoescovers the productionFilterForApiExportpath 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.ScanRuntimenow fails on exported constructs it does not model, including exported interfaces with bodies. ExperimentalPolyglotGotest 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.
|
Pull request created: #1980
|
|
📝 Documentation has been drafted in microsoft/aspire.dev#1980 targeting Added a "Export Go API reference data" entry to the Aspire 17.0 what's-new page. Triggered signals: Note This draft PR needs human review before merging. |
…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
#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>
> [!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

Note
Merge order: no PR must land before this one. It overlaps #21197, which adds the same
AtsTypeSystemCompatibility.csand changes two generator members that this exporter calls. They merge without textual conflicts, but whichever lands second needs a two-line fix-up inAtsGoCodeGenerator.ApiProjection.cs, described in #21197.Description
aspire sdk export --language gofails 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 itsAtsJsonGeneratorre-implements the Go generator's naming and type mapping, so it can drift from whatAtsGoCodeGeneratorreally emits, and a dump cannot see the surface the generator writes by hand:Build()on the builderInteractionInputCollectionhelpers (Get,Required,Value,RequiredValue)Err()on every handle andToMap()on options structsbase.goruntime typesopts ...*XxxOptionsflattening and the callback func typesThe export projects through the generator's own naming and type-mapping code, so aspire.dev can consume
aspire sdk export -l gofor signatures instead of re-deriving them.Part of #21115.
What changes
AtsGoApiReferenceExporter(new) implementsIApiReferenceExporterfor Go. It is a separate type fromAtsGoCodeGeneratoron purpose, as in the TypeScript exporter.Aspire.TypeSystemis force-shared with a frozenAssemblyVersion, so an older CLI binds this assembly but its copy ofAspire.TypeSystemhas noIApiReferenceExporter, and a type that implements the interface cannot load there.CodeGeneratorResolversalvages the loadable types, so such a CLI keeps generating Go and only loses the export.AtsGoCodeGeneratorbecomespartial(one word inAtsGoCodeGenerator.cs). The newAtsGoCodeGenerator.ApiProjection.csbuilds 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.GoDeclarationScannerreads the hand-written Go that the generator itself emits (thebase.goruntime and the builder entry point) instead of keeping a hand-maintained list, so that surface cannot drift either.GoApiModelandGoApiExportWriterhold the model and write the document. The writer builds aJsonNodetree and the exporter returnsJsonDocument.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 readsAtsCapabilityInfo.IsExperimentalreflectively so a newer generator still runs against an olderAspire.TypeSystem. The TypeScript project keeps its own copy.--languagehelp ofaspire sdk exportreads(e.g., typescript, go), anddocs/specs/cli-output-formats.mddescribes the Go export next to the TypeScript one. Go resolves through the same language discovery as the other languages, so it needs the existingexperimentalPolyglotGofeature.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'simportPath),modules[](name,items[]) anddeclarations[](id,owningAssembly,content).items[].kindisinterface,augmentation(members a package adds to a type that another package declares),dto,options,enum,variable,functionortype.members[].kindismethod,fieldorconstant. Every member has the exact Go text indeclaration. Capability-backed members carrycapabilityId, and members that the generator writes itself are markedsynthesized. Methods also carryerrorModel(none,returnedordeferred),experimentalanddeprecatedmarkers where they apply, and anoptionsblock (the struct type and its fields) when the method takes the trailingopts ...*XxxOptions.Trimmed excerpt of the Redis export.
AddRedisshows the trailing options flattening andToMap()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.Hostingand the Go generator are this checkout's.Aspire.Hosting.Redis@13.6.1Err()x3,ToMap()x7)Aspire.Hosting.Azure.Storage@13.6.1Aspire.Hosting(core)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-modulesdata (13.6.0), compared by exact Go signature:Aspire.Hosting.RedisAspire.Hosting.Azure.StorageAspire.Hosting(core)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
mainon its own and is independent of the godoc PR ("Emit godoc from ATS documentation metadata in the Go SDK generator"). Both changeAtsGoCodeGenerator.csin different places, and both addsrc/Shared/CodeGeneration/AtsTypeSystemCompatibility.cswith 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
BuildDocumentationMapsand anincludeDocsparameter toRenderGoExportedValueType:AtsGoCodeGenerator.ApiProjection.cs,BuildApiModel: addBuildDocumentationMaps(context);directly afterBuildNameMaps(context);, so documentation rendering during the projection has its maps.ProjectExportedValues: callRenderGoExportedValueType(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
Aspire.Hosting, a project reference (1,068 of 1,609).Aspire.Hosting), as in generation. An app that combines many integrations can get a different disambiguation suffix where two packages collide.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.ApiReferenceExportTestsandCodeGenerationResolverTests(RemoteHost) resolve and run the Go exporter throughCodeGenerationService. The existing "language without an exporter" test uses Python instead of Go, since Go ships an exporter.SdkExportCommandTests(CLI) checks thatsdk export --language goresolves the Go generator when the feature is enabled.Follow-ups
typeandoptionalto DTO fields and constants (fromAtsDtoPropertyInfo.IsOptional). Today the type is only inside the memberdeclaration, and every DTO field carriesomitempty.aspire sdk export -l go, which removes the return-type and nullable differences above.functionsandappliesToview. The dump-derived reference lists one signature per capability, while the export repeats a member per concrete interface.Validation
.\restore.cmddotnet 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"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"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"dotnet run --project tools/SelectTests -- --from upstream/main --to HEAD --explainaspire sdk export --language go --package Aspire.Hosting.Redis@13.6.1aspire sdk export --language go --package Aspire.Hosting.Azure.Storage@13.6.1aspire sdk export --language goupstreamis the microsoft/aspire remote. The three exports ran in a directory whoseaspire.config.jsoncontains{"features":{"experimentalPolyglotGo":true}}, withDOTNET_ROOTpointing at this checkout's.dotnetandASPIRE_CLI_TELEMETRY_OPTOUT=1. Stdout is the JSON document only. Times are wall clock on a developer machine.The new Verify snapshots (
GoApiExportTests.FocusedApiExport,GoOnlySurfaceandAugmentingPackage) were reviewed before they were accepted.Conditional test selection: the selector selects
Aspire.Cli.EndToEnd.Tests,Aspire.Cli.Tests,Aspire.Hosting.CodeGeneration.Go.TestsandAspire.Hosting.RemoteHost.Testsand triggerscli-starter-validation,extension-e2e,polyglotandtypescript-api-compat. The new files live in projects the trigger map already covers, and the linked shared file is attributed by the project graph, soeng/github-ci/test-trigger-map.ymlneeds no change.Not verified:
Aspire.Cli.TestsandAspire.Hosting.RemoteHost.Testssuites. Only the classes above ran. The TypeScript exporter and the other languages' generators are not touched and were not run.aspire sdk export --language gowithexperimentalPolyglotGooff 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 answersNo 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).Aspire.Hosting.Checklist
<remarks />and<code />elements on your triple slash comments?