Skip to content

Emit godoc from ATS documentation metadata in the Go SDK generator - #21197

Merged
David Pine (IEvangelist) merged 9 commits into
mainfrom
ievangelist-go-codegen-docs
Oct 30, 2026
Merged

David Pine (IEvangelist) merged 9 commits into
mainfrom
ievangelist-go-codegen-docs

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. #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.
  • Add aspire sdk export -l go (Go API reference exporter) #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:

// 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:

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 Add aspire sdk export -l go (Go API reference exporter) #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. Add aspire sdk export -l go (Go API reference exporter) #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.
    • 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

Move AtsTypeSystemCompatibility from the TypeScript generator into src/Shared/CodeGeneration and link it into the TypeScript and Go generators, so the Go generator can read AtsCapabilityInfo.IsExperimental without a hard dependency on a member older Aspire.TypeSystem builds lack.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
The Go generator took doc comments almost only from capability descriptions plus a few hard-coded lines, so gopls hover and pkg.go.dev showed little of the XML documentation that C# authors wrote. Documentation, enum-value, deprecation and experimental metadata now flow through every emission site: capabilities, parameters and trailing options, returns, handle types, DTOs and their fields, enums and each enum value, exported values and Options structs.

GoDocComment renders the model following https://go.dev/doc/comment: a comment starts with the identifier name, paragraphs are separated by a bare // line, Deprecated: is its own paragraph (the only marker gopls and staticcheck recognise), preformatted text is an indented block and [Name] links are written only for declared identifiers. Experimental capabilities get a "# Experimental" heading with a Notice paragraph, the convention grpc-go uses for experimental APIs. CR, CRLF and U+2028 in XML-doc text can never end a comment.

Go-only tests cover a hand-built documented model, the formatter output, hostile input, godoc invariants on the real SDK and, when the Go toolchain is installed, go build, go vet and gofmt comment stability. The two whole-SDK snapshots grow because every documented member now carries its documentation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Capability ids, parameter names and property names are spliced into Go string literals, struct tags, map keys and identifiers. A quote, backslash, line break or percent sign in that metadata produced Go that does not compile or that ends a literal early.

GoStringLiteral now quotes every metadata string at those sinks, the unexpected-type error format doubles '%' in the capability id, and ToPascalCase sanitizes its result because every caller emits it as an identifier. Doc comments are covered by GoDocComment, which prefixes every line with '//' and treats CR, LF and CRLF as line breaks. Output for valid names is unchanged, so no existing snapshot changes.

A hand-built hostile context is snapshot-tested and run through go build and go vet.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
The relaxed JSON writer spells a character outside the Basic Multilingual
Plane as a UTF-16 surrogate pair, for example "\uD83D\uDE00" for U+1F600.
Go rejects surrogate halves in a string literal, so an exported string
value, enum value, untyped value or dictionary key containing such a
character made `go build` fail for the whole generated SDK.

Quote string values and dictionary keys with GoStringLiteral, which writes
those characters as UTF-8. Numbers and booleans are unchanged because they
are the same text in JSON and Go.

The hostile-metadata test now exports a non-BMP string, dictionary key,
enum value and untyped value, so both the Verify snapshot and the go
build/vet check cover the sink.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
go/doc/comment treats a one-line paragraph between two paragraphs as a
heading when it starts with a capital letter, ends with a letter or digit
and has no disallowed character. A period followed by a non-space and a
possessive "'s" are allowed in a heading, so "Requires Redis 7.2" and
"Used with the resource's name" were still rewritten by gofmt into
"# Heading" even though the guard skipped them.

Only the characters that disqualify a heading exempt a remark from the
guard now. The appended period is harmless and keeps the text a paragraph.
The generated SDK snapshots are unchanged because none of the scanned
remarks is such a paragraph.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
GoStringLiteral also quotes exported string values and keeps surrogate
pairs as UTF-8, and the fmt.Errorf format helper leaves ids without '%'
untouched. go/printer only reformats doc comments that start in column 1,
so the gofmt round trip covers top-level declarations; tab-indented
interface-method and struct-field comments are covered by the targeted
heading test instead.

Comments only; no behavior change.

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

Or

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

@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot October 20, 2026 07:32
@github-actions github-actions Bot added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Oct 20, 2026
@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.

🟢 Approval recommended

No blocking issues remain, and focused snapshots and toolchain tests cover the changed behavior; tests were not rerun here.

No open issues 🎉

What changed in this PR

Adds richer Go SDK documentation from ATS metadata, supporting Go AppHost readiness, and hardens generated source escaping.

Changes:

  • Emits godoc summaries, remarks, parameter docs, and lifecycle notices.
  • Escapes metadata and exported string values safely for Go.
  • Shares the compatibility probe and adds regression coverage.
File Description
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​GoDocCommentRender.verified.txt Captures formatter output.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​EscapedMetadataGeneratedAspire.verified.go Captures escaped metadata.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​DocumentedMetadataGeneratedAspire.verified.go Captures documented declarations.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​AtsGeneratedAspire.verified.go Updates generated documentation.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​GoGeneratorEscapingTests.cs Tests hostile metadata and Unicode escaping.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​GoDocCommentTests.cs Tests formatting and Go toolchain compatibility.
src/​Shared/​CodeGeneration/​AtsTypeSystemCompatibility.cs Shares the version-skew probe.
src/​Aspire.Hosting.CodeGeneration.TypeScript/​AtsTypeScriptCodeGenerator.cs Imports the shared probe namespace.
src/​Aspire.Hosting.CodeGeneration.TypeScript/​Aspire.Hosting.CodeGeneration.TypeScript.csproj Links the shared probe.
src/​Aspire.Hosting.CodeGeneration.Go/​GoDocComment.cs Implements godoc formatting.
src/​Aspire.Hosting.CodeGeneration.Go/​AtsGoCodeGenerator.cs Integrates documentation and escaping.
src/​Aspire.Hosting.CodeGeneration.Go/​Aspire.Hosting.CodeGeneration.Go.csproj Links the shared probe.

Review effort: Balanced

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

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

Resolve the single conflict, the Go two-pass-scanning snapshot (TwoPassScanningGeneratedAspire.verified.go), by regenerating it from the merged tree instead of hand-merging the 45K-line generated file. The regenerated snapshot picks up main's TerminalOptions DTO and WithTerminal(options ...*WithTerminalOptions) changes (#21116) rendered with this PR's godoc comments. Ignoring comment and blank lines it is identical to main's snapshot.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@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

Generator-wide escaping and shared compatibility changes warrant human confirmation of the reported toolchain validation, which was not independently run during this review.

No open issues 🎉

Review effort: Balanced

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

@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

SDK-wide formatting and source-emission changes warrant human review because the reported Go build, vet and formatting results were not independently verified.

No open issues 🎉

Review effort: Balanced

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

David Pine (IEvangelist) added a commit that referenced this pull request Oct 28, 2026
…every resource (#21193)

## Description

A freshly scaffolded Go AppHost had several rough edges: the SDK that
the CLI regenerates under `.aspire/` was not ignored by git,
`apphost.go` was not gofmt-clean, the scaffold output, the `go-starter`
template and the generated SDK files took CRLF line endings on Windows,
the launch profile ports came from a range that overlaps the Windows
dynamic port range, 49 sample AppHosts used a `log.Fatalf` call that `go
vet` rejects, and the starter's `builder.Err()` check could not see a
failed `AddRedis` or `AddGoApp`.

- **Ignore the generated SDK.** `GoLanguageSupport.Scaffold` now also
writes a `.gitignore` containing `.aspire/`, where the CLI regenerates
the SDK (`.aspire/modules`; it is large and rebuilt from the AppHost's
integrations). The `go-starter` template gets the same one-line file,
like the TypeScript, Python and Java starters, and
`TemplateGitIgnoreTests` has a `go-starter` row. In a directory that
already has a `.gitignore`, `ScaffoldingService` keeps it and appends
only the missing entries (`MergeGitIgnoreContent`).
- **gofmt-clean `apphost.go`.** The scaffold listed `"log"` before
`"apphost/modules/aspire"` in one import group, which gofmt reorders,
and ended without a final newline, which gofmt adds (a C# raw string
literal drops the last newline). It now has two import groups and ends
with a newline.
- **LF line endings at the source.** gofmt rewrites a CRLF `.go` file,
and three producers wrote CRLF on Windows. The scaffold's string
literals take the line endings of the C# source (`apphost.go`, `go.mod`,
`apphost.run.json`). The `go-starter` template is embedded and
scaffolded exactly as it is checked out. The generated SDK files
(`go.mod`, `transport.go`, `base.go`, `aspire.go`) mix raw string
literals, `StringWriter` output and embedded resources. `Scaffold` now
converts every file it returns to LF, `GenerateDistributedApplication`
replaces CRLF with LF at its single exit point, and `.gitattributes`
pins `*.go` and the `go-starter` directory to LF. The generator replaces
only `\r\n`: `ReplaceLineEndings` would also split at U+2028, form feed
and NEL, which Go allows inside comments and strings, and the generated
doc comments carry the description text of the exported APIs.
- **Launch profile ports.** `apphost.run.json` drew four ports from
`random.Next(10000, 65000)`, which overlaps the Windows dynamic port
range (49152-65535). It now uses `AppHostProfilePortGenerator`, which
the CLI templates and the TypeScript scaffold already use. Its fixed
ranges all end below 22300 (dashboard 15000-15299 http and 17000-17299
https, OTLP 19000-19299 and 21000-21299, resource service 20000-20299
and 22000-22299). The shared file is linked into the Go code generation
project.
- **Sample AppHosts pass `go vet`.** 408
`log.Fatalf(aspire.FormatError(err))` calls in 49
`tests/PolyglotAppHosts/*/Go/apphost.go` files became
`log.Fatal(aspire.FormatError(err))`. `go vet` reports `non-constant
format string in call to log.Fatalf` for the old form, and a `%` in an
error message would be printed as a formatting verb. The edit is one
token per line with line endings and BOMs unchanged, and no
`Fatalf(aspire.FormatError` remains in the tree.
- **Playground comment.** The example comment in
`playground/GoAppHost/apphost.go` said `AddRedis("cache", nil, nil)`,
which no longer matches the generated signature, where optional
parameters are a trailing options struct. It now says
`AddRedis("cache")`.
- **Check every resource handle.** A child-returning call such as
`AddRedis` or `AddGoApp` that fails records its error on the handle it
returns, not on the builder, and `Build()` checks only the builder's own
error, so the `builder.Err()` check in the template could not see it.
The `go-starter` `apphost.go` now keeps the `api` handle and checks
`Err()` on `cache` and `api` before `Build()`. The `aspire init` example
comment shows the same loop, with `AddRedis` and `AddPostgres`. The
template has no `{{token}}` placeholders, so `aspire new
aspire-go-starter` writes this file as it is, and the `apphost.go` on
the Go AppHost page in microsoft/aspire.dev#1924 is the same text.
- **Tests.** `GoScaffoldTests` (new, 15 test cases) covers the exact
scaffold file set, LF line endings of the scaffold output and of the
`go-starter` files, a `.gitignore` that ignores only `.aspire/`, the
`go.mod` module, go, require and replace directives, the launch profile
ports staying inside the shared generator ranges (five port seeds,
including `null`), language detection on the scaffolded files, and
gofmt-cleanliness of the scaffold output and of the `go-starter` sources
as checked out. `AtsGoCodeGeneratorTests` gets
`GenerateDistributedApplication_WritesFilesWithLfLineEndings`. The Go
code generation test project links every `go-starter` file as a test
input, plus the shared `TemporaryWorkspace` helper. No
`eng/github-ci/test-trigger-map.yml` change is needed:
`tests/PolyglotAppHosts/**` already routes to the polyglot job, the
`go-starter` files are a `None Include` that the project graph sees, and
`.gitattributes` already routes to every target, so this PR selects
every test target. The handle check has no test of its own: nothing pins
the content of the starter `apphost.go` or of the `aspire init` comment,
and `ScaffoldedAndStarterSources_AreGofmtClean` covers their formatting.

Part of #21115

### Not in this PR

- Making the generated SDK (under `.aspire/modules`) gofmt-exact. About
30 emit sites write single-line blocks such as `if x != nil { ... }`,
struct and const alignment differs, and the imports are space-indented,
so `gofmt -l` lists the file. It is git-ignored and regenerated on every
restore, and fixing it means changing those emit sites and re-accepting
every generated-SDK snapshot.
- Running `go vet` over the sample AppHosts in CI.
- The `experimentalPolyglotGo` header comment in
`playground/GoAppHost/apphost.go`, which goes away with the feature flag
(#21106).

## Validation

Commands ran on Windows from the worktree root, on top of
`upstream/main` `5ea175ce62` at head `de7b79d7d2`, with the repo-local
SDK.

| Command | Exit | Result |
| --- | --- | --- |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.Go.Tests\Aspire.Hosting.CodeGeneration.Go.Tests.csproj
--no-restore --no-launch-profile -- --filter-not-trait
"quarantined=true" --filter-not-trait "outerloop=true"` | 0 | 49 passed,
0 failed, 0 skipped |
| `dotnet test --project tests\Aspire.Cli.Tests\Aspire.Cli.Tests.csproj
--no-restore --no-launch-profile -- --filter-class
"*.TemplateGitIgnoreTests" --filter-class "*.NewCommandTests"
--filter-class "*.NewCommandTemplateConfigPersistenceTests"
--filter-class "*.ScaffoldingServiceTests" --filter-not-trait
"quarantined=true" --filter-not-trait "outerloop=true"` | 0 | 165
passed, 0 failed, 0 skipped |
| `git grep -n "Fatalf(aspire.FormatError" HEAD` | 1 | no match (`git
grep` exits 1 when nothing matches) |

The Go run includes all of `GoScaffoldTests`. A `--list-tests` check
showed the Cli run includes the new `go-starter` row of
`TemplateGitIgnoreTests`.

Test-first check for the scaffold LF change: the two new tests
`Scaffold_WritesFilesWithLfLineEndings` and
`ScaffoldedAndStarterSources_AreGofmtClean` were run on their own, in a
CRLF working tree, against the scaffold as it was before the
`ReplaceLineEndings` line was added (the other changes already in
place). Both failed (2 run, 2 failed). The first reported `apphost.go`,
`go.mod` and `apphost.run.json` as containing CR. The second reported
`gofmt -l` listing the scaffolded `apphost.go` with a whole-file diff.
With the change both pass. This also shows that the gofmt test really
runs gofmt when the tools are present. Running `gofmt -d` (Go 1.27.0) on
a minimal file with the previous single import group, and on one without
a final newline, confirms the other two fixes: gofmt moves
`"apphost/modules/aspire"` above `"log"` and adds the missing final
newline.

Test-first check for the starter and generator LF change:
`GoStarterFiles_UseLfLineEndings` and
`GenerateDistributedApplication_WritesFilesWithLfLineEndings` were run
on their own against the source without this change, in a CRLF working
tree. Both failed (2 run, 2 failed). With the change both pass, as part
of the 49 above. Negative control: with the two new `.gitattributes`
rules removed and the starter files re-created,
`GoStarterFiles_UseLfLineEndings` and
`ScaffoldedAndStarterSources_AreGofmtClean` failed again (the second
with a gofmt diff of `go-starter/api/main.go`). With the rules restored
and the files re-created, `git ls-files --eol` lists all 8 starter files
as `i/lf w/lf attr/text eol=lf` and every test passes. The gofmt test
now reads the starter files exactly as they are checked out, without
converting them first.

`ScaffoldedAndStarterSources_AreGofmtClean` is marked
`[RequiresTools(["go", "gofmt"])]`. When a tool is missing the attribute
adds the `category=failing` trait, and the CI test runner filters that
trait out (`eng/Testing.targets`), so the test is left out there rather
than failed. `GeneratedTransport_SupportsDuplexCommunication` in the
same project already works this way with `[RequiresTools(["go"])]`. The
two new LF tests need no external tool and run everywhere.

`go vet` over the 53 sample AppHosts (Go 1.27.0). The first run
generated one SDK from the union of all the samples' packages (80
packages) with a locally built Debug CLI and vetted every sample against
it.

- Before the change: 4 clean, 32 `non-constant format string in call to
log.Fatalf`, 17 type errors.
- After the change: 36 clean, 0 format string failures, the same 17 type
errors.
- The 17 type errors appear only in the shared SDK. Each of those 17 was
vetted again against an SDK generated from only its own packages (in a
scratch copy of `tests/PolyglotAppHosts/<Sample>/Go`: `aspire restore
--non-interactive --apphost apphost.go`, then `go vet ./...`): 17 of 17
clean.
- The scaffolded `apphost.go` with its `go.mod`, and the `go-starter`
AppHost, were vetted the same way and also build with `go build ./...`
(exit 0).

The CLI for these runs was a locally built Debug CLI from an earlier
`main` (`3ed7e9690b`) plus an unrelated Go `aspire docs api` commit, not
a build of this branch's base. The five commits between that `main` and
`5ea175ce62` touch neither the Go or TypeScript code generators, the
shared code generation, the type system, the remote host, nor any Go
sample. These runs also predate the LF commits and the rebase onto
`5ea175ce62`; none of them changes the content of the samples or of the
generated SDK, only its line endings.

Handle check and end-to-end runs (head `de7b79d7d2`). The first checks
used a generated SDK that has `AddRedis`, `AddGoApp` and `AddPostgres`,
from an earlier CLI build (this PR does not touch those APIs or
`Resource.Err()`). The `go-starter` `apphost.go` with its `go.mod`
builds and vets (`go build`, `go vet`, Go 1.27.0, both exit 0) and
`gofmt -l` lists nothing. The `aspire init` example comment, uncommented
in a scratch `main.go` with a `[]aspire.Resource{cache, db}` slice, also
builds and vets, and it is the text of the `Scaffold` raw string with
the comment markers removed (compared as strings). The `apphost.go`
fence on the Go AppHost page in microsoft/aspire.dev#1924 is
byte-identical to the template once line endings are normalized.

Then I built the CLI from this head and ran it on Windows (a Debug build
that targets net11.0, run as `dotnet aspire.dll` with the repo-local
runtime; Go 1.27.0 with `GOTOOLCHAIN=local`, `GOWORK=off` and
`GOPROXY=off`). The Go starter is still behind
`features__experimentalPolyglotGo` until #21106 lands, so I set it.
`aspire new` needed `--version 17.0.0-dev`: without it the CLI looks for
a local `Aspire.ProjectTemplates` package of its own version and finds
none.

- `aspire new aspire-go-starter --version 17.0.0-dev --name verifygo
--non-interactive --suppress-agent-init` exited 0. The `apphost.go` it
wrote is byte-identical to the template (1224 bytes, LF only, no BOM),
`.gitignore` is exactly `.aspire/`, and all 8 starter files have no CR.
In that project `gofmt -l` lists nothing, and `go build ./...` and `go
vet ./...` exit 0 against the SDK the command generated.
- `aspire init --language go` in an empty directory exited 0 and wrote
`.gitignore` (`.aspire/`), `apphost.go` with the new handle-loop
comment, `go.mod` and `aspire.config.json`. The Go files and
`.gitignore` have no CR and no BOM, `gofmt -l` lists nothing, and `go
build ./...` and `go vet ./...` exit 0. `aspire.config.json` has CRLF on
Windows because `AspireConfigFile.Save` uses the platform newline for
every language; this PR does not change that.
- A failed `Add` call at run time. In a copy of the starter I renamed
the Go app to `"cache"`, the name of the Redis resource, so `AddGoApp`
fails on the server (`Cannot add resource of type
'Aspire.Hosting.Go.GoAppResource' with name 'cache' because resource of
type 'Aspire.Hosting.ApplicationModel.RedisResource' with that name
already exists`). With the new loop, `aspire run --apphost apphost.go
--isolated --non-interactive` stopped before `Run()`, printed that
message and `exit status 1`, and the CLI reported `The Go apphost
failed`. In a second copy that skipped the loop and wrote the results to
a file, `builder.Err()` was nil, `cache.Err()` was nil, `api.Err()` held
that message and `Build()` returned nil, so a check of `builder.Err()`
alone does not see the failure.

Overlap with open PRs: this PR shares files with #21183
(`playground/GoAppHost/apphost.go`), #21187 (`GoLanguageSupport.cs`),
#21188 (`AtsGoCodeGenerator.cs`, `AtsGoCodeGeneratorTests.cs`), #21194
(`AtsGoCodeGeneratorTests.cs`), #21195 and #21197
(`AtsGoCodeGenerator.cs`, `Aspire.Hosting.CodeGeneration.Go.csproj`) and
#21199 (`AtsGoCodeGenerator.cs`). A trial merge (`git merge-tree
--write-tree`) of this head with the head of each of those seven PRs
(`0e65752d44`, `e1bb4c11ae`, `9088dfe7fb`, `ffc59f2023`, `7d33810c11`,
`82a44b0723`, `4f5a7a84aa`) was clean, as was a trial merge with each of
the other open Go AppHost PRs and with `upstream/main` `f4ae2cc424`.

Not run:

- `aspire init --language go` in a directory that already has a
`.gitignore` or a `go.mod`. The run above used an empty directory. The
`.gitignore` merge has two unit tests
(`MergeGitIgnoreContent_AppendsMissingEntriesWithoutOverwritingExistingContent`
and
`MergeGitIgnoreContent_DoesNotAddDuplicateAspireEntryWhenEquivalentEntryAlreadyExists`).
- The LF changes are observable only on CRLF inputs. On a Linux or macOS
checkout the LF tests pass with or without them, and I ran on Windows
only. A working tree checked out before the `.gitattributes` rule keeps
CRLF in the `go-starter` files, because git does not rewrite existing
files when an attribute changes, so `GoStarterFiles_UseLfLineEndings`
fails there until the files are re-created (delete the `go-starter`
directory and run `git checkout -- <directory>`). Fresh checkouts are
not affected. Whether the official build checks the `go-starter` files
out as LF or CRLF was not checked; the rule makes it LF either way.
- The rest of `Aspire.Cli.Tests`, the CLI end-to-end tests, and the
polyglot validation scripts under
`.github/workflows/polyglot-validation`. `test-go.sh` there scaffolds
with `aspire init --language go` and inserts code before the
`builder.Build()` line; the scaffold keeps that line and both imports.
- `go vet` over the 53 sample AppHosts with a CLI built from this head.
Only the starter and the `aspire init` scaffold were run with it.
- The output of the 36-sample union SDK vet run was not saved to a file,
so only the per-sample runs above can be repeated from the description.

## 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
    - 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
David Pine (IEvangelist) added a commit that referenced this pull request Oct 28, 2026
…ons (#21188)

> [!NOTE]
> **Merge order:** no PR must land before this one. It overlaps two open
PRs, and whichever lands second rebases:
>
> - #21194 adds tests at the same place in `AtsGoCodeGeneratorTests.cs`.
> - #21197 changes the union helpers next to `GetUnionAllowedTypes` in
`AtsGoCodeGenerator.cs` and two snapshots. Keep both sets of helpers and
re-accept the snapshots with `dotnet verify accept -y`.

## Description

A Go AppHost that passes an options struct holding a callback panics
when the options are merged, for example `AddManifestOptions{Configure:
...}` from #18080:

```
panic: aspire: merge error: unexpected end of JSON input
```

Every generated Go method that takes `...*XxxOptions` merges its options
with `deepUpdate` before serializing them. `deepUpdate` merged through a
JSON round trip and discarded the marshal error. `encoding/json` cannot
marshal a `func` value, even a nil one, so any options struct with a
callback field failed, and `*CancellationToken` (`json:"-"`) was
silently dropped. This is not specific to `AddManifest`: the same path
breaks every Configure-style option in the generated SDK (Kubernetes
`AddManifest` and `WithHelm`, the Azure Container Apps and App Service
`PublishAs*` options, `InteractionProgressOptions` and the validation
callbacks). The polyglot validation job only `go build`s those fixtures,
so none of these paths was ever executed.

- **`deepUpdate` merges by reflection** (`Resources/base.go`). Struct
fields and map entries present on both sides merge recursively. Any
other value, including nil, is taken from the later option, as before. A
struct with unexported fields (such as `*CancellationToken`) is opaque
and is taken whole. Neither argument is modified. For a small options
struct this is about 6-15x faster than the JSON round trip, with about
10x fewer bytes and 17-33x fewer allocations (Go 1.27 micro-benchmark).
- **Go numeric values are accepted by number unions**
(`AtsGoCodeGenerator.cs`). Go boxes the constant `3` as `int`, but the
generated union guard for a parameter that allows an ATS number only
accepted `float64`, so `WithField(path, 3)` failed with `parameter
"value" must be one of [string, float64, bool], got int`. The type
switch now accepts every Go numeric type when `float64` is a union
member. They all serialize as JSON numbers. Without this the publish in
#18080 could not set an integer such as `maxReplicaCount: 3`, even after
the panic was fixed.

Part of #18080. This fixes Bug 1 only, so it does not close the issue.

### Not in this PR

Bug 2 of #18080 (`WithField` only accepts scalar values and dot-notation
paths, so nested specs and keys that contain dots, such as
`app.kubernetes.io/component`, cannot be expressed) is not Go-specific.
`KubernetesManifestResource.WithField` is limited by
`[AspireUnion(string, double, bool)]`, which the server enforces for
every language, while `NormalizeManifestValue` already handles arrays
and objects. The proposal is to drop the union so `value` is `any`, with
an additive `withFieldJson(path, json)` overload as the fallback. That
is an API-shape decision for every polyglot SDK and needs API review and
a dispatch test, so it is left out here.

### Behavior notes

- A later option's nil field still overwrites an earlier non-nil value.
This is unchanged.
- A nil map now stays nil. The JSON round trip turned it into an empty
map.
- The merged result can share a map with one of its inputs when the
other side is nil.
- Named numeric types such as `time.Duration` are still rejected by the
union guard. Only the predeclared numeric types are accepted.

## Validation

| Command | Result |
| --- | --- |
| `.\restore.cmd` | 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"` | 34 passed, 0 failed, 0 skipped |

The new `GeneratedRuntime_PassesGoTests` writes the generated runtime to
a temp directory, adds Go tests for the merge semantics and the numeric
union guard, and runs `go test` on it. It uses the same
`[RequiresTools(["go"])]` gate as the existing
`GeneratedTransport_SupportsDuplexCommunication`. A Go-only test export
(`GoTestExtensions.cs`, `WithScalarField`) exercises the union guard
through the real generator. Two Verify snapshots are refreshed.

Red/green: with the generator from before this change,
`GeneratedRuntime_PassesGoTests` fails with 11 rejections of `got int`.

End to end with a real Go AppHost, using a Debug-built CLI with
`ASPIRE_REPO_ROOT` pointing at this branch. The AppHost calls
`AddManifest` with a `Configure` callback that sets a label, an
annotation, a string field and `WithField("spec.maxReplicaCount", 3)`:

| Runtime | Result |
| --- | --- |
| This branch | `aspire publish` exits 0 with 10/10 pipeline steps and
writes `templates\kube-service\scaler.yaml`, a `keda.sh/v1alpha1`
`ScaledObject` with the label, annotation and `maxReplicaCount: 3` as an
integer |
| `base.go` from before this change | `panic: aspire: merge error:
unexpected end of JSON input` from `deepUpdate` via `AddManifest`, "The
connection to the AppHost was lost", `aspire publish` exits 6 |

Not verified:

- Python, Java and Rust callback options. They were read from snapshots
only.
- The polyglot validation job and the full CI matrix. CI is the first
run there.

## 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
    - 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
David Pine (IEvangelist) added a commit that referenced this pull request Oct 28, 2026
…21199)

> [!NOTE]
> **Merge order:** no PR must land before this one. It overlaps #21197
in `AtsGoCodeGenerator.cs` (private fields in the same block) and
`TwoPassScanningGeneratedAspire.verified.go`. Whichever lands second
keeps both sets of fields and re-accepts the snapshot with `dotnet
verify accept -y`.

## Description

In the generated Go SDK, a builder of a derived resource type cannot be
passed where an AppHost API takes its base resource type. Every handle
interface re-declares its fluent methods with its own return type, and
Go has no return-type covariance, so the derived interface does not
satisfy the base interface. Embedding the base interface in the derived
one is not possible either, because the same method names would be
declared with different return types.

For example, `AddNodePool` on an AKS environment returns
`AksNodePoolResource`, and `WithNodePool` takes
`KubernetesNodePoolResource`:

```go
aks := builder.AddAzureKubernetesEnvironment("aks")
pool := aks.AddNodePool("workload")
builder.AddContainer("api", "nginx").WithNodePool(pool)
```

```text
cannot use pool (variable of interface type aspire.AksNodePoolResource) as aspire.KubernetesNodePoolResource value in argument to builder.AddContainer("api", "nginx").WithNodePool: aspire.AksNodePoolResource does not implement aspire.KubernetesNodePoolResource (wrong type for method ExcludeFromManifest)
	have ExcludeFromManifest() aspire.AksNodePoolResource
	want ExcludeFromManifest() aspire.KubernetesNodePoolResource
```

`WithNodePool` is declared on 163 builders.
`AzurePromptAgentResource.WithTool(FoundryToolResource)` rejects all
three Foundry tool builders (`AddAISearchTool`,
`AddCodeInterpreterTool`, `AddWebSearchTool`) the same way.

### Change

For every concrete handle type `T` that at least one other concrete
handle type derives from, the generator emits one small interface,
`AnyT`, meaning "`T` or anything derived from `T`". `AnyT` replaces `T`
where the caller supplies a value:

```go
// AnyKubernetesNodePoolResource accepts KubernetesNodePoolResource or a handle of any type derived from it.
type AnyKubernetesNodePoolResource interface {
	handleReference
	isKubernetesNodePoolResource()
}

func (s *aksNodePoolResource) WithNodePool(nodePool AnyKubernetesNodePoolResource) AksNodePoolResource
```

A type whose base type also has an accepting interface declares the base
marker too, so an `AnyT` value converts to the `Any` interface of each
base type. From the 62-integration SDK described below:

```go
// AnyAzureProvisioningResource accepts AzureProvisioningResource or a handle of any type derived from it.
type AnyAzureProvisioningResource interface {
	handleReference
	isAzureBicepResource()
	isAzureProvisioningResource()
}
```

- `AnyT` embeds `handleReference` and declares the unexported marker
method `isT()` plus the marker of each base type of `T` that has an
accepting interface, sorted by name. The handle interface of `T` and of
every type derived from `T` declares the same markers, and the matching
implementation types implement them. Go converts one interface value to
another only when the method set of the source has every method of the
target, so the base markers are what let a helper that holds an
`AnyAksPoolResource` pass it on to a parameter typed `AnyPoolResource`.
No interface is embedded.
- `AnyT` is used only where the caller supplies a value: method
parameters, options-struct fields, DTO fields, union members, and slice
and read-only map element types. Return types, receivers and callback
signatures are unchanged, so `pool.WithPoolPeer(other)` still returns
the receiver's own type.
- The check stays at compile time. The markers are unexported, so only
handle types of the same family satisfy `AnyT`, and user code cannot add
to the family. The family is directional: an `AnyAksPoolResource` value
is accepted where `AnyPoolResource` is expected, an `AnyPoolResource`
value is still rejected where `AnyAksPoolResource` is required, and a
builder of an unrelated type is rejected for both. Every handle
interface is already sealed to the SDK package in the same way by the
unexported `getHandle` method of `handleReference`, so this adds no new
cross-package restriction.
- Which types get an interface is decided in one place,
`BuildAcceptingInterfaces` in `AtsGoCodeGenerator.cs`, from the
base-type hierarchy the scanner already records, and input positions
pick it up through one mapping function, `MapInputTypeRefToGo`. Names go
through the generator's existing `ReserveName`, so they cannot collide
with another generated type name, and no reflection or dynamic code is
involved. The cost is one interface per base type, one marker
declaration and one marker method per handle type and ancestor base, and
one marker line in each `AnyT` for `T` and for each of its accepting
base types, so it grows linearly with the SDK.

Alternatives that were rejected:

- **Map those parameters to the broad `Resource` marker interface.**
This is the smallest change, but every builder satisfies it, so a wrong
resource kind (for example a Foundry account passed to `WithTool`) is
only rejected by the AppHost server at run time instead of at compile
time.
- **Generate converters such as `AsKubernetesNodePoolResource()`.** This
adds a public method per derived and base type pair and needs a wrapper
or an RPC to implement, and every caller has to know to call it wherever
Go would otherwise reject the builder.

### Scope

Measured on a generated SDK for 62 integrations (64 packages: the
database and messaging integrations, the language hosting packages,
Foundry, and the Azure hosting packages including AKS). The "Before"
column is the generator on `main`.

| | Before | After |
| --- | --- | --- |
| `aspire.go` lines | 475,458 | 476,847 (+1,389) |
| `aspire.go` bytes | 22,590,205 | 22,665,827 (+75,622, +0.33%) |
| Accepting interfaces | 0 | 15 |
| Marker declarations in handle interfaces / marker methods on handle
types | 0 / 0 | 342 / 342 |
| Marker lines inside the accepting interfaces: own type / base types |
0 / 0 | 15 / 3 |
| Parameter sites typed as a base that has derived types | 170 as `T` |
170 as `AnyT` |
| Compiler view of the SDK package: lines / functions | 477,323 / 73,264
| 478,712 / 74,020 |

The deterministic counts bound the cost to about 1% more compiler
functions. On a 3-integration SDK (Kubernetes, AKS, Foundry) `aspire.go`
grows from 4,617,498 to 4,631,727 bytes (+0.31%).

Timings on the shared machine are noise (the second run of each pair is
the faster one). They were taken with the first commit of this change,
which emits 3 fewer marker lines than the head: cold compile of the SDK
package (2 alternating runs, compiler `-bench` total) 33.6 s and 23.1 s
on `main`, 28.9 s and 18.1 s with the change; code generation time (RPC)
for the 64 packages 680 ms on `main`, 644 ms with the change; median
cold `go build` of the 3-integration SDK over 3 alternating runs 5.93 s
on `main`, 5.79 s with the change. One cold compile of the SDK package
at the head took 22.0 s.

All 170 sites are by-value method parameters: `WithNodePool` on 163
builders, and seven single-builder methods, `WithTool`, `Unsubscribe`,
`SetProperties`, `SetAuthProperties`, `SetConnection`, `SetSource` and
`ResourceIdentifier`. The last five take `*Proxy` handle types (for
example `ResourceIdentifier(resource ProvisionableResourceProxy)`),
which the same rule covers beyond the two reported defects. No
options-struct, DTO, union or collection site is affected in this SDK;
the new fixture covers those positions.

Seven of the 15 interfaces (`AnyContainerResource`, `AnyProjectResource`
and five others) have no parameter site in this SDK. They are generated
anyway so the rule has a single definition that does not depend on API
usage, and the set of names depends only on the type hierarchy. They
account for 274 of the 684 marker lines added to handle interfaces and
implementations. Three of the 15 interfaces declare a base marker
(`AnyAzureProvisioningResource`, `AnyJavaScriptAppResource` and
`AnyPythonAppResource`). All three are among those seven, so no existing
parameter changes, and passing an `AnyT` value on to an `AnyBase`
parameter is covered by the fixture and by a type-level probe (see
Validation).

### Compatibility

- Existing call sites that pass a builder directly compile unchanged:
every value that satisfied `T` satisfies `AnyT`, because the interface
of `T` declares the marker. This covers all 170 parameter sites in the
62-integration SDK. Go does not convert `[]T`, `map[string]T` or `*T` to
`[]AnyT`, `map[string]AnyT` or `*AnyT`, and a user-declared interface or
function type that spells the old parameter type no longer matches the
method, so code in one of those shapes switches to `AnyT`. No API in the
62-integration SDK has a slice, map or pointer parameter of such a type.
- A helper that declares its own parameter, field or variable as
`aspire.T` and must also hold a derived builder uses `aspire.AnyT`.
`AnyT` carries no fluent methods; it is for passing a builder into an
API, and the derived builder's own methods configure it. A helper
written over a family can take `aspire.AnyAksPoolResource` and pass it
on to an API that takes `aspire.AnyPoolResource`.
- No C# public API changes. The generated Go SDK gains the exported
`Any*` interface types.

### Known limitations

- Mutable `*List[T]` and `*Dict[K, V]` keep a concrete element type,
because Go generics are invariant (a `*List[AnyT]` is not a `*List[T]`).
Adding a derived builder to such a list still does not compile. No API
in the 62-integration SDK has such a site for a base type that has
derived types.
- An optional handle parameter is a pointer field in its options struct,
so it becomes `*AnyT` (it is `*T` on `main`). The generated runtime does
not serialize a pointer to an interface as a handle (`serializeValue`
passes the pointer through unchanged), for `*AnyT` and for `*T` alike,
so this change neither fixes nor worsens that. No API in the
62-integration SDK has an optional parameter, DTO field or union member
of such a type.
- A union parameter stays typed `any` with a run-time check, and the
check accepts derived builders.

### Not in this PR

- A live AppHost run with a derived builder. The AppHost server converts
a handle argument with `IsInstanceOfType` and `IResourceBuilder<out T>`
is covariant, so a derived handle takes the same path as a base handle.
This PR proves the Go types, not the round trip.
- The Go API reference on aspire.dev keeps its own copy of the type
mapping, so it shows `T` for these parameters until the same rule is
added there.

### Overlap with #21197

Both changes add private fields in the same block of
`AtsGoCodeGenerator.cs` and both change
`TwoPassScanningGeneratedAspire.verified.go`. A trial merge conflicts
only in that one code hunk, which is resolved by keeping both sets of
fields, and in the snapshot, which the second PR to merge re-accepts
with `dotnet verify accept -y`.

Part of #21115

## Validation

All commands ran on Windows with the repo-local SDK and Go 1.27.0, on
top of `main` at `5ea175ce62`. The two compile tests need `go` on `PATH`
and use the same `RequiresTools` gating as the existing generated-SDK
compile test.

| Command | Exit | Result |
| --- | --- | --- |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.Go.Tests\Aspire.Hosting.CodeGeneration.Go.Tests.csproj
--no-launch-profile -- --filter-class "*.AtsGoDerivedBuilderTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"`, run against the unchanged generator | 2 | 8 failed, 0
passed |
| same command, with the change | 0 | 8 passed, 0 failed |
| `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 | 41 passed, 0 failed (8 new,
33 existing) |

Without the change, all 8 tests fail: the compile test reports `cannot
use aks (variable of interface type aspire.AksPoolResource) as
aspire.PoolResource value ... (wrong type for method WithPoolPeer)` and
the string tests find no `Any*` interface. If the `Any*` interfaces list
only their own marker, the compile test fails instead with `cannot use p
(variable of interface type aspire.AnyAksPoolResource) as
aspire.AnyPoolResource value in argument to workload.WithPool:
aspire.AnyAksPoolResource does not implement aspire.AnyPoolResource
(missing method isPoolResource)`. The new tests use a Go-only fixture
built in the test file, so the shared TypeScript test types are
untouched: a four-level pool hierarchy (`PoolResource`,
`AksPoolResource` derived from it, `SpotPoolResource` derived from that,
`GpuSpotPoolResource` derived from that), an unrelated queue resource,
and capabilities that take the base as a required parameter, an optional
parameter (options struct), a DTO field, a union member, a slice
element, a read-only map element, a mutable list element and a callback
parameter. Six tests inspect the generated Go text. Two compile the
generated SDK with `go build`: one passes the derived builders where the
base is expected, checks that fluent calls keep returning the receiver's
own type, and passes `AnyAksPoolResource` and `AnySpotPoolResource`
values on to parameters typed with the `Any` interface of the type
itself and of each base type; the other asserts that exactly three
errors are reported: a queue passed to `WithPool`, a base pool passed to
`WithAksPool`, and an `AnyPoolResource` value passed where an
`AnyAksPoolResource` is required. One of the six text tests scans the
real hosting model and checks that the `TestRedisResource` handle, which
derives from `ContainerResource`, declares and implements the
`AnyContainerResource` marker. Another covers a base type that
capabilities reference but the model's handle-type list omits: it still
declares and implements its own marker, so its values satisfy `AnyT`.

The only snapshot that changes is
`TwoPassScanningGeneratedAspire.verified.go`: 4 `Any*` interfaces, 10
marker declarations, 10 marker implementations, and exactly one changed
parameter site, `DistributedApplicationEventing.Unsubscribe(subscription
AnyDistributedApplicationEventSubscription)` in the interface and in the
implementation (2 removed lines, 59 added non-blank lines). None of the
four `Any*` interfaces in that model has an accepting base type, so each
declares only its own marker.

Real SDK for Kubernetes, AKS and Foundry: the commands run in a
directory whose `aspire.config.json` lists `Aspire.Hosting.Kubernetes`,
`Aspire.Hosting.Azure.Kubernetes` and `Aspire.Hosting.Foundry` and sets
`features.experimentalPolyglotGo`, with `ASPIRE_REPO_ROOT` pointing at
this repository so the AppHost server builds the generator under test.
The probes are the two snippets above, a negative case, and a type-level
forwarding probe, each a small package in the AppHost module. The
forwarding probe declares `takesBicep(r aspire.AnyAzureBicepResource)`
and `forward(r aspire.AnyAzureProvisioningResource) { takesBicep(r) }`.

| Command | Generator on `main` | With the change |
| --- | --- | --- |
| `aspire restore --apphost apphost.go --non-interactive` | exit 0 (39
s), 0 `Any*` interfaces | exit 0 (43 s), 8 `Any*` interfaces |
| `go build ./probes/nodepool` (`AddNodePool` result passed to
`WithNodePool`) | exit 1, `aspire.AksNodePoolResource does not implement
aspire.KubernetesNodePoolResource (wrong type for method
ExcludeFromManifest)` | exit 0 |
| `go build ./probes/foundrytool` (AI Search, Code Interpreter and Web
Search tool builders passed to `WithTool`) | exit 1, 3 errors, one per
tool builder | exit 0 |
| `go vet ./probes/nodepool`, `go vet ./probes/foundrytool` and `go vet
./probes/anyforward`, each run separately | not run | exit 0 each |
| `go build ./probes/anyforward` (an `AnyAzureProvisioningResource`
value passed on to a parameter typed `AnyAzureBicepResource`) | not run
(no `Any*` types) | exit 0 |
| `go build ./probes/foundryneg` (a Foundry account passed to
`WithTool`) | not run | exit 1, `aspire.FoundryResource does not
implement aspire.AnyFoundryToolResource (missing method
isFoundryToolResource)` |

Against an SDK generated with each `Any*` interface listing only its own
marker, `go build ./probes/anyforward` and `go vet ./probes/anyforward`
both exit 1 with `aspire.AnyAzureProvisioningResource does not implement
aspire.AnyAzureBicepResource (missing method isAzureBicepResource)`.

Source compatibility for existing callers: 85 Go AppHosts converted from
the C# samples (kept outside the repository), compiled against the
62-integration SDK generated by each generator.

| Command | Exit, SDK from `main` | Exit, SDK with the change | Result |
| --- | --- | --- | --- |
| `go build -gcflags=-e ./conv/...` | 1 | 1 | one failing package,
`pg_certmanager`, with identical errors on both |
| `go vet ./conv/...` | 1 | 1 | same package, same error |

The failing package calls `WithLetsEncryptProductionParam`, which
neither SDK exports. The other 84 packages build and vet clean against
both SDKs.

The counts in the Scope table come from a throwaway script over the two
generated `aspire.go` files, and are not part of this PR.

`eng/github-ci/test-trigger-map.yml` needs no change: the tests are in
the existing `Aspire.Hosting.CodeGeneration.Go.Tests` project, and the
generator is in `Aspire.Hosting.CodeGeneration.Go`, which the map
already routes to the polyglot job.

Not run:

- Wall-clock timings at the head of this branch. The timings in "Scope"
come from the first commit, which emits 3 fewer marker lines in the
62-integration SDK; only a single cold compile of the SDK package (22.0
s) was taken at the head.
- An existing API call that passes an `AnyT` value on to an `AnyBase`
parameter. No API in the 62-integration SDK has that shape, so it is
covered by the fixture and the `anyforward` type-level probe only.
- Linux and macOS.
- Go versions other than 1.27.0 (the SDK declares `go 1.26`).
- A live AppHost run with a derived builder (see "Not in this PR").
- Integrations outside the 62-integration set.
- The rendered output of the aspire.dev Go API reference.
- GitHub CI for 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
    - 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
David Pine (IEvangelist) added a commit that referenced this pull request Oct 28, 2026
> [!NOTE]
> **Merge order: land this PR after the other open Go generator PRs.**
It does not depend on any of them and is based on `main`, but it changes
files that #21188, #21193, #21194, #21195, #21197 and #21199 also change
(`AtsGoCodeGenerator.cs`, `Resources/base.go`, the Go generator tests
and the two Go snapshots).
>
> - When this PR was opened it merged cleanly (`git merge-tree`) with
every other open Go AppHost PR except #21197. The one conflict is two
lines in `EmitDtoCallbackToMap`: keep #21197's `GoStringLiteral(...)`
line and this PR's `clientExpression: null` argument.
> - If the Go snapshots conflict or go stale after another PR lands,
regenerate them by running the Go codegen test project twice, because
Verify rewrites the snapshots on the first run.
> - #21188 also rewrites `deepUpdate`, which fixes the options-struct
panic described under "Not covered".

## Description

In a Go AppHost, a callback whose parameter is a resource builder
(`Action<IResourceBuilder<T>>` in C#) received a nil value, so the first
call on it panicked. The host marshals callback arguments with the
declared parameter type, so a closed generic `IResourceBuilder<T>` is
sent with a closed-generic `$type` (`Type.FullName`, which embeds the
assembly-qualified `T`), while a builder returned from a capability is
sent with the plain id of `T`. The generated Go SDK registers wrappers
only for plain ids, so the transport left the raw handle in place and
`callbackArg[T]` fell back to the zero value of `T`, a nil interface.

The generated callback shim now builds the wrapper from the declared
parameter type instead of relying on `$type`, which is what the
TypeScript generator already does.

Fixes #21255

### Before and after

A Go AppHost from `aspire-go-empty` plus `Aspire.Hosting.Docker`, run
through `aspire publish` with the Go generator and runtime from `main`
versus this branch:

```go
env := builder.AddDockerComposeEnvironment("env")
env.ConfigureDashboard(func(dashboard aspire.DockerComposeAspireDashboardResource) {
	dashboard.WithHostPort(&aspire.WithHostPortOptions{Port: aspire.Float64Ptr(9003)})
})
```

| | Before | After |
|---|---|---|
| Callback argument | nil | usable
`DockerComposeAspireDashboardResource` |
| `aspire publish` | `panic: runtime error: invalid memory address or
nil pointer dereference`, the Go AppHost exits with status 2 and the CLI
exits with code 6 | exit 0, all 7 steps succeed, `docker-compose.yaml`
maps `9003:18888` on `env-dashboard` |

### What changed

- Go runtime (`Resources/base.go`): `callbackHandleArg[T](c, args, idx,
wrap)` returns `wrap(h, c)` when the argument is still a raw `*handle`
and otherwise defers to `callbackArg[T]`, so values the transport
already wrapped (plain resource and context ids) take the path they took
before.
- Generator (`AtsGoCodeGenerator`): a callback shim emits
`callbackHandleArg(s.client, args, i, new<Interface>FromHandle)` for a
handle-category parameter that has a generated constructor and a client
in scope. DTOs, enums, `CancellationToken` and DTO property callbacks
(which have no client) keep `callbackArg[T]`.
- Tests: a generator test that pins the emitted wrapper for
`PublishAsDockerFile`, and a Go-backed test (`[RequiresTools(["go"])]`)
that compiles the generated SDK and drives a callback over an in-memory
fake host with both a closed-generic and a registered `$type`. Both fail
on the old generator.
- Snapshots: regenerated.

### Reviewer notes

- **The snapshot diff is one mechanical transform.**
`callbackArg[X](args, N)` becomes `callbackHandleArg(s.client, args, N,
newXFromHandle)` at 260 call sites (259 changed lines) in
`TwoPassScanningGeneratedAspire.verified.go` and 11 call sites (10
changed lines) in `AtsGeneratedAspire.verified.go`, plus the 17-line
helper in the latter (it embeds `base.go`). Applying the inverse
transform to the new snapshots reproduces the files on `main` byte for
byte. Only the four `PublishAsDockerFile` shims for `ContainerResource`
(executable, dotnet tool, project and C# app) change behavior in those
snapshots; every other site is a context or event type that already
arrived wrapped.
- **More exports are fixed than the issue lists.** Across hosting and 19
integration assemblies, 27 declared `IResourceBuilder<T>` callback
parameters expand to 29 shims that were affected, for example
`WithDashboard` (Docker Compose and Kubernetes), `WithRedisInsight`,
`WithPgAdmin`, `WithMongoExpress`, `WithKafkaUI` and the Azure
`RunAsEmulator` and `RunAsContainer` overloads.
- **Not covered.**
- `ConfigureEnvFile` on Docker Compose takes `Action<IDictionary<string,
CapturedEnvironmentVariable>>` and has a related cause: its dictionary
argument still arrives as a zero-value `*Dict` with no handle behind it,
so using it panics. It is the only dictionary-typed callback parameter
in the 53 generated Go validation SDKs. A small generator change that
wraps it the same way worked in a local check; it is left out so this PR
stays about resource builders.
- DTO property callbacks have no client in scope; none of them takes a
resource builder today.
- Callbacks passed through an options struct (the project and C# app
`PublishAsDockerFile` overloads, and `ConfigureContainer` on Redis
`WithRedisInsight` and `WithRedisCommander`) panic earlier, in
`deepUpdate`, on `main` with or without this change. #21188 rewrites
`deepUpdate`. With a local workaround for `deepUpdate`, the Redis
callbacks received nil before this change and a live wrapper after it;
none of these overloads was run on a tree that contains #21188.
- Java appears to have the same weakness (read, not run). TypeScript and
Python already use the declared parameter type for the wrapper.
- No CI job runs a Go callback at runtime: `polyglot-validation.yml`
only compiles the Go validation AppHosts. The new Go-backed test covers
the transport against an in-memory fake host.
- Not run: Linux and macOS, `aspire run` with the dashboard UI (the
checks below use `aspire publish`, and the `PublishAsDockerFile`
callback does not run in run mode), `go test -race` (no C compiler on
the machine), and Rust.
- **Host-side alternative not taken.** Marshalling the plain resource
type id would fix every guest at once, but it changes the wire contract
that `CallbackProxyTests` pins.

### Validation

Windows, Go 1.27.0, Docker 29.9.1. The `dotnet test` runs are on the
final commit. The Go AppHost checks ran on the same change before a
clean rebase onto the current `main` (the patch is identical).

- `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"`: 35 passed, 0 failed, 0 skipped (33
on `main`). Run twice, and `git status` was clean after each run, so the
snapshots are stable.
- The same project with the old `AtsGoCodeGenerator.cs` and `base.go`
under the new tests and snapshots: 4 failed (both new tests and both
snapshot tests).
- `dotnet test --project
tests/Aspire.Hosting.RemoteHost.Tests/Aspire.Hosting.RemoteHost.Tests.csproj
--no-launch-profile -- --filter-class "*.CodeGenerationResolverTests"
--filter-class "*.IntegrationLoadContextTests" --filter-class
"*.ApiReferenceExportTests" --filter-class "*.ServiceErrorMessageTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` (the classes that resolve the Go generator): 27
passed, 0 failed.
- Real Go AppHosts built with `aspire new aspire-go-empty`, then `aspire
restore` and `aspire publish`, before and after:
- `ConfigureDashboard` with `WithHostPort(9003)`: panic and CLI exit 6,
then exit 0 with all 7 steps and `9003:18888` on `env-dashboard`.
- `PublishAsDockerFile(func(c aspire.ContainerResource) {...})` on an
executable: panic and CLI exit 6, then a live wrapper whose calls
(entrypoint, environment, and `WaitFor` with the wrapper as an argument)
all appear in the compose file.
- 15 callbacks whose `$type` is a registered id
(`WithEnvironmentCallback`, `WithArgsCallback`, `SubscribeBeforeStart`
and others): the generated compose files are identical before and after.
- All 53 Go validation AppHosts under `tests/PolyglotAppHosts` pass
`aspire restore` and `go build` with this generator.
- A throwaway in-package test of `callbackHandleArg` (not committed): 14
observations, and 64 goroutines x 2000 calls with no bad results.

## 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
    - 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
Resolve the conflicts with the Go generator changes that landed on main
(#21188 union and callback fix, #21199, #21261 accepting interfaces):

- AtsGoCodeGenerator.cs: keep both sets of private fields and helpers.
  BuildNameMaps builds the accepting interfaces first and the documentation
  maps last. The enum constant name comes from main's
  GetEnumMemberConstantName, the doc block and GoStringLiteral escaping stay.
  The union allowed-types doc note also reports that float64 accepts any
  built-in Go numeric type, matching main's widened type switch.
- Regenerate the three affected snapshots from the merged generator. Their
  non-comment, non-blank lines are identical to main's.

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

Copy link
Copy Markdown
Contributor

Tests selector

7 / 100 PR test projects · 7 PR jobs, from 14 changed files.

Selected PR test projects (7 / 100)

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

Selected PR jobs (7)

cli-starter-validation, extension-e2e, homebrew-installer, polyglot, typescript-api-compat, typescript-sdk, winget-installer


How these were chosen — grouped by what changed

🔧 src/Aspire.Hosting.CodeGeneration.TypeScript/Aspire.Hosting.CodeGeneration.TypeScript.csproj (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.TypeScript.Tests
→ 3 via the project graph: Aspire.Cli.Tests (2 hops), Aspire.Hosting.Native.Core.Tests (2 hops), Aspire.Managed.Tests (2 hops)

🔧 src/Aspire.Hosting.CodeGeneration.Go/Aspire.Hosting.CodeGeneration.Go.csproj (changed source)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests
→ 1 via the project graph: Aspire.Hosting.RemoteHost.Tests

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

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

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

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

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

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

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

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

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/AtsGeneratedAspire.verified.go (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/DocumentedMetadataGeneratedAspire.verified.go (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/EscapedMetadataGeneratedAspire.verified.go (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/GoDocCommentRender.verified.txt (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

Job reasons

Job Triggered by
cli-starter-validation • affected project Aspire.Hosting.Native.Server
• affected project Aspire.Hosting.CodeGeneration.TypeScript
extension-e2e • src/Aspire.Hosting.CodeGeneration.TypeScript/Aspire.Hosting.CodeGeneration.TypeScript.csproj, src/Aspire.Hosting.CodeGeneration.TypeScript/AtsTypeScriptCodeGenerator.cs, src/Aspire.Hosting.CodeGeneration.TypeScript/AtsTypeSystemCompatibility.cs
• affected project Aspire.Hosting.Native.Server
• affected project Aspire.Hosting.CodeGeneration.TypeScript
homebrew-installer affected project Aspire.Hosting.Native.Server
polyglot affected project Aspire.Hosting.CodeGeneration.Go
typescript-api-compat affected project Aspire.Hosting.CodeGeneration.Go
typescript-sdk affected project Aspire.Hosting.CodeGeneration.TypeScript
winget-installer affected project Aspire.Hosting.Native.Server

Selection computed for commit 45de07f.

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.

🟢 Approval recommended

No active review issues remain for the generated Go SDK documentation and escaping changes.

No open issues 🎉

Review effort: Balanced

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

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

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

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. b0bca0d resolves my earlier concern: BuildNameMaps now builds the documentation maps itself, so any caller, including the #21195 exporter, gets a usable _docs. That leaves only the compiler-enforced includeDocs: false as the merge fix-up.

I re-checked the merge with the Go PRs that have since landed (#21188, #21199, #21261 and others). The new sibling code that writes to the SDK still emits only sanitized identifiers in comments, and every metadata string literal still goes through GoStringLiteral. Aspire.Hosting.CodeGeneration.Go.Tests passes locally on this head (79/79, Go toolchain tests included).

LGTM, approving.

David Pine (IEvangelist) added a commit that referenced this pull request Oct 30, 2026
> [!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:

```json
{
  "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" }
    ]
  }
}
```

```json
{
  "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 (#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.
  - [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
@IEvangelist
David Pine (IEvangelist) merged commit 3dde72b into main Oct 30, 2026
844 of 857 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: #1981

Generated by PR Documentation Check · copilot · auto · 20 AIC · ⌖ 1.03 AIC · ⊞ 7.1K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

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

Adds a "Documentation in the SDK" section to go-apphost.mdx describing godoc now emitted in aspire.go. Signals: polyglot_code_generator_changed (AtsGoCodeGenerator.cs, GoDocComment.cs), pr_body_has_cli_flag_mention, pr_body_has_deprecation_marker (Deprecated:/Experimental conventions).

Note

This draft PR needs human review before merging.

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
Sébastien Ros (sebastienros) added a commit to microsoft/aspire.dev that referenced this pull request Nov 13, 2026
Documents changes from microsoft/aspire#21197

Author: ``@davidfowl-unknown-placeholder``

Targeting `release/17.0` — the latest release branch on
`microsoft/aspire.dev` — because the source PR has no milestone or
`release/*` base ref to derive a more specific target
(`candidate_source`: `fallback_main`).

## Why
The Go SDK generator now emits godoc from ATS documentation metadata
(summary, remarks, parameters, returns, `Deprecated:`, `# Experimental`,
doc links). The Go AppHost docs did not mention this.

## Changes
- Updated `src/frontend/src/content/docs/app-host/go-apphost.mdx`: new
"Documentation in the SDK" subsection under "Generated SDK".

Triggered signals: `polyglot_code_generator_changed`,
`pr_body_has_cli_flag_mention`, `pr_body_has_deprecation_marker`.

> Generated by [PR Documentation
Check](https://github.com/microsoft/aspire/actions/runs/40991758835) for
#21197 · copilot · auto · 20 AIC · ⌖ 1.03 AIC · ⊞ 7.1K ·
[◷](https://github.com/search?q=repo%3Amicrosoft%2Faspire.dev+%22gh-aw-workflow-id%3A+pr-docs-check%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Documentation Check, engine: copilot,
model: auto, id: 40991758835, workflow_id: pr-docs-check, run:
https://github.com/microsoft/aspire/actions/runs/40991758835 -->

<!-- gh-aw-workflow-id: pr-docs-check -->
<!-- gh-aw-workflow-call-id: microsoft/aspire/pr-docs-check -->

---------

Co-authored-by: aspire-repo-bot[bot] <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Co-authored-by: Sébastien Ros <1165805+sebastienros@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants