You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Accept derived builders where the Go SDK takes a base resource type - #21199
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:
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:
// AnyKubernetesNodePoolResource accepts KubernetesNodePoolResource or a handle of any type derived from it.typeAnyKubernetesNodePoolResourceinterface {
handleReferenceisKubernetesNodePoolResource()
}
func (s*aksNodePoolResource) WithNodePool(nodePoolAnyKubernetesNodePoolResource) 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:
// AnyAzureProvisioningResource accepts AzureProvisioningResource or a handle of any type derived from it.typeAnyAzureProvisioningResourceinterface {
handleReferenceisAzureBicepResource()
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.
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.
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) }.
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?
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?
The interface of a derived Go handle type does not satisfy the interface of its
base type: each interface re-declares the fluent methods with its own return
type and Go has no return-type covariance. A parameter typed as a base resource
builder (for example ContainerResource.WithNodePool taking
KubernetesNodePoolResource) rejected the derived builder that the matching
factory returns (AksNodePoolResource).
Each concrete handle type that another handle type derives from now gets an
Any<Type> interface (AnyKubernetesNodePoolResource) that embeds handleReference
and one unexported marker method. Every concrete handle of the type and of its
derived types implements the marker. The Any<Type> interface is used only where
the caller supplies a value: method parameters, options struct fields, DTO
fields, union members, and slice and read-only map elements. Return types,
callback signatures and mutable List and Dict element types keep the concrete
type, and the fluent interface of every handle is unchanged. The marker keeps
the check at compile time, so a builder outside the family still does not
compile.
Tests use a Go-only fixture, so the shared TypeScript test types are untouched.
They assert the emitted interfaces, the marker sets and the parameter
positions, and compile a generated SDK with go build for a derived builder
passed as its base and a negative case for an unrelated builder.
Part of #21115
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
An Any<Type> interface declared only the marker of its own type, so a value
typed AnyAksPoolResource could not be passed where AnyPoolResource is expected:
Go converts one interface type to another only when the source declares every
method of the target. A helper written over a family of builders could not
forward its parameter to an API typed with the accepting interface of a base
type.
Each Any<Type> now also declares the marker of every base type that has an
accepting interface, the same ordered list the concrete handle interfaces and
implementations already use. Nothing is embedded and no public type is added.
The check stays at compile time: an unrelated builder, and an Any<Base> value
where an Any<Derived> is required, still do not compile.
The marker list is now built for every type that has an implementation, so a
base type that capabilities reference but HandleTypes does not list still
declares and implements its own marker. Without that, the lookup added for the
accepting interfaces would have no entry for such a type.
The Go-only fixture gains a fourth level (GpuSpotPoolResource) so an accepting
interface with two ancestors is covered; the existing SpotPoolResource was a
leaf and had no accepting interface. The compile test forwards
AnyAksPoolResource and AnySpotPoolResource values to base-typed parameters, the
negative compile test rejects a downward conversion, and the marker test
asserts the exact body of each accepting interface. The real-model snapshot
changes by one generated comment line.
Part of #21115
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
The reason will be displayed to describe this comment to others. Learn more.
Thanks, this is a clean approach. Unexported markers keep the check at compile time, AnyT appears only in input positions, and fluent return types are unchanged. The tests cover the hierarchy, the forwarding case and the negative cases well. I also ran Aspire.Hosting.CodeGeneration.Go.Tests on macOS arm64 with Go 1.26.2: all 41 tests pass, including the two go build compile tests.
I left a few comments inline. The integration-set dependency of the Any* names is the one worth thinking about. The others are minor, and any of them can be a follow-up or a small update before merge.
One cross-PR note, already mentioned in the description: this overlaps #21197 in the private-field block of AtsGoCodeGenerator.cs and in TwoPassScanningGeneratedAspire.verified.go, so whichever PR merges second needs to re-accept that snapshot.
The generated header now notes that the Any<Type> set depends on the integrations an AppHost includes, a comment records why DTO fields map like inputs, and the optional handle options field is pinned to *AnyPoolResource in the test.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
GenerateExportedValues emits each catalog root verbatim as a package-level var,
but those names were not reserved, so an exported value named like an accepting
interface (for example AnyPoolResource.Default next to a PoolResource hierarchy)
produced both `var AnyPoolResource` and `type AnyPoolResource` and failed to
compile. Reserve the roots before allocating the Any* names so ReserveName picks
a numeric suffix for the interface instead, leaving every earlier name intact.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Enum-name collisions and missing ancestor markers for omitted intermediate types can still cause generated Go code or valid callers to fail compilation.
If an intermediate type such as AksPoolResource is omitted from HandleTypes but still referenced by capabilities, both its handle interface and AnyAksPoolResource lose the ancestor marker isPoolResource(). Passing either to WithPool(AnyPoolResource) then fails compilation, even though descendant hierarchies record that ancestry. Recover the omitted type's ancestors from those chains and add a regression case that omits an intermediate base.
GenerateEnumTypes emits each enum member as a package-level const named
after the enum and the member, for example AnyPool + Resource becomes
AnyPoolResource. Those names were never reserved, so a base handle type
PoolResource whose accepting interface is also AnyPoolResource made the
generated SDK fail with "AnyPoolResource redeclared in this block".
Reserve the enum member constant names alongside the options struct and
exported value names before the accepting interface names are allocated,
so a colliding interface takes the next free name. The constant name is
built by one helper shared with the emitter, so the two cannot drift.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The reason will be displayed to describe this comment to others. Learn more.
🟢 Approval recommended
No unresolved blocking issues remain, and focused regression coverage addresses inheritance, forwarding, and the previously reported naming collisions.
…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
> [!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
Documents the generated Go SDK Any<Type> accepting interfaces in go-apphost-conventions.mdx. Triggered signals: polyglot_code_generator_changed (AtsGoCodeGenerator.cs) and pr_body_has_cli_flag_mention.
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>
…21197)
> [!NOTE]
> **Merge order:** no PR must land before this one. #21188 and #21199,
which overlapped it, are on main and this branch contains them.
Whichever of the remaining open PRs lands second rebases:
>
> - A PR that changes `TwoPassScanningGeneratedAspire.verified.go` (a
new or changed `Aspire.Hosting` API reaches it) conflicts with this one
there, because this PR adds doc comments throughout the file. Regenerate
the snapshot with `dotnet verify accept -y` instead of merging hunks by
hand. `AtsGeneratedAspire.verified.go` works the same way.
> - #21195 calls `RenderGoExportedValueType`, whose signature this PR
changes, so the second to land needs a one-line fix-up in
`AtsGoCodeGenerator.ApiProjection.cs`.
## Description
Part of #21115.
The Go SDK generator documents a member only from the capability
`Description`, plus a few fixed comments for enums, DTOs and handles.
`Summary`, `Remarks`, `Returns`, per-parameter docs, enum value docs and
the obsolete and experimental flags never reach `aspire.go`, so `go doc`
and gopls hover show one thin line or nothing. This PR emits godoc from
the same ATS documentation metadata the TypeScript generator already
turns into JSDoc.
### What changes in the generated SDK
Documentation flows to every kind of declaration:
- Capabilities (handle methods, standalone functions, property getters
and setters): summary, remarks, a `Parameters:` list and a `Returns:`
paragraph. A trailing `...Options` parameter points at its Options
struct, and each Options field carries the doc of its parameter.
- Handle interfaces, DTO structs and their fields, enum types and each
enum value, exported value groups and their members, and Options
structs.
The comments follow godoc conventions:
- A comment starts with the identifier it documents, paragraphs are
separated by a bare `//`, and code samples and lists from the XML docs
keep an indented-block form. Lines are wrapped near 80 columns and never
split a word.
- `<see cref>` references become `[Name]` doc links only for generated
types. Anything else stays plain text so the SDK has no dangling links.
- Obsolete capabilities end with a `Deprecated:` paragraph, the one
marker gopls and staticcheck recognize.
- Experimental capabilities get a `# Experimental` heading and the line
`Notice: This API is EXPERIMENTAL and may be changed or removed in a
later release.` Go has no toolchain-recognized experimental marker, so
this uses the convention `google.golang.org/grpc` documents its
experimental APIs with. It renders as a heading on pkg.go.dev and in
gopls hover and is stable under gofmt. TypeScript uses `@experimental`.
- XML-doc text is normalized to LF and no comment line has trailing
whitespace.
- A one-line remarks paragraph that gofmt and `go doc` would read as a
heading, such as `Requires Redis 7.2` or `Used with the resource's
name`, ends with a period so it stays a paragraph.
Example from the test snapshot. On main this method has only the first
line:
```go
// WithPreviewStatus sets the preview status.
//
// Parameters:
// - status: The status to set.
//
// # Experimental
//
// Notice: This API is EXPERIMENTAL and may be changed or removed in a later
// release.
//
// Deprecated: Use WithDocumentation instead.
WithPreviewStatus(status DocumentedStatus) DocumentedResource
```
### Commits
1. **Share the ATS version-skew probe between polyglot generators.**
`AtsTypeSystemCompatibility` (reads the experimental flag from an
`Aspire.TypeSystem` that may predate it) moves from the TypeScript
generator project to `src/Shared/CodeGeneration` and is linked into the
Go and TypeScript generator projects. The TypeScript generator only
gains a `using`.
2. **Emit godoc from ATS documentation metadata in the Go SDK
generator.** New `GoDocComment.cs` formats a comment from the metadata,
and `AtsGoCodeGenerator.cs` calls it at each declaration.
3. **Escape ATS metadata at the Go generator output sinks.** Injection
hardening, described below.
4. **Render exported string values as Go string literals.** The same
sink class for exported values, described below.
5. **End one-line remarks that gofmt would turn into headings with a
period.** See the conventions list above.
6. **Make the escaping and gofmt round-trip comments state what they
cover.** Comments only.
7. **Build the Go doc maps with the name maps.** `BuildNameMaps` builds
the documentation maps itself, so a caller that builds only the name
maps still gets a usable renderer (review feedback).
### Escape ATS metadata at the Go generator output sinks
ATS metadata (descriptions, capability ids, parameter and property
names) was spliced into Go source unescaped. A multi-line description,
or a name containing a quote, a newline or a percent sign, produced Go
that did not compile or that carried extra statements. Now:
- every doc comment line is prefixed with `//`: CR, LF and CRLF start a
new comment line, and Unicode line and paragraph separators, control
characters and the byte order mark are replaced or dropped, so a
description cannot end the comment;
- string literals (capability ids, request argument names, json struct
tags, map keys, enum constant values and `%q` arguments) go through one
`GoStringLiteral` helper, and a capability id inside a `fmt.Errorf`
format string has its `%` doubled;
- method names (`ToPascalCase`) go through the existing
`SanitizeIdentifier`, as parameter and type names already did;
- exported string values, enum values and dictionary keys go through
`GoStringLiteral` too (see the review finding below).
This is a low-severity robustness fix. An integration author already
runs code on the developer's machine, so no trust boundary is crossed.
Output for valid first-party names is unchanged: the hardening commits
change no snapshot that exists on main. The shared scanner and the other
language generators have the same pattern and are left for a follow-up.
A review of this change found one more sink of the same class, rated
Medium and fixed by commit 4. Exported string values, enum values and
dictionary keys were written with the relaxed JSON writer, which spells
a character outside the Basic Multilingual Plane (for example an emoji)
as a UTF-16 surrogate pair such as `\uD83D\uDE00`. Go rejects surrogate
halves in a string literal, so one such value failed `go build` for the
whole SDK with `escape is invalid Unicode code point U+D83D`. These
values now go through `GoStringLiteral`, which keeps such characters as
UTF-8. Numbers and booleans are the same text in JSON and Go and render
as before.
### Generated output and cost
- Two-pass SDK (`aspire.go` for `Aspire.Hosting` plus the test types):
1,347,950 to 1,808,456 bytes (+34.2%) and 31,892 to 45,393 lines. The
smaller test-types snapshot: 162,529 to 176,209 bytes (+8.4%) and 4,591
to 5,049 lines.
- The sequence of non-comment, non-blank lines in both large snapshots
is identical to main (27,526 and 3,730 lines compared, 0 differences).
The snapshot diffs are doc comment lines and the blank lines that
separate them.
- Markers in the two-pass snapshot: `Deprecated:` 16, `# Experimental`
221, `Parameters:` 848, `Returns:` 789.
- Generation time, scan excluded, 1 warm-up and 15 samples on a shared
developer machine: median 16.0 ms on main and 104.2 ms with this change
(+88 ms), min 12.8 ms and 85.7 ms. This was measured before main's
latest Go generator changes were merged and not repeated. The cost is
linear in the number of documented identifiers and the regular
expressions are source-generated. It was not profiled further.
Review tip: read `DocumentedMetadataGeneratedAspire.verified.go`,
`EscapedMetadataGeneratedAspire.verified.go` and
`GoDocCommentRender.verified.txt` first. The two large snapshot diffs
are comments only.
### Tests and guard
New tests are in `GoDocCommentTests.cs` and
`GoGeneratorEscapingTests.cs`. They build their metadata in code, so the
TypeScript `TestTypes` that the Go, Java, Python and Rust test projects
link are untouched.
- `GenerateDistributedApplication_WithDocumentedMetadata_EmitsGodoc`
(Verify snapshot) covers every declaration kind above, including
`Deprecated:`, `# Experimental`, enum values, special characters and
CRLF input.
- `Render_FormatsGodocBlocks` (Verify snapshot) covers the comment
formatter, and `Render_KeepsEveryLineInsideTheComment` proves hostile
text never leaves the `//` comment.
`Render_EndsHeadingLookingRemarksWithAPeriod` proves that one-line
remarks which `go/doc/comment` would read as a heading (gofmt rewrites
them to `# Heading`) end with a period.
- `GeneratedSdk_DocCommentsFollowGodocConventions` is the guard that
documented APIs keep their docs: over the SDK generated from the real
scanned `Aspire.Hosting` assembly, every commented declaration starts
with its name, no line has trailing whitespace or a lone CR,
`Deprecated:` starts its own paragraph, obsolete and experimental
metadata present in the model reaches the output, and the documented
enum values equal the commented constants. The two-pass snapshot also
covers the whole SDK, so an XML-doc edit to a scanned `Aspire.Hosting`
API changes it, the same coupling the TypeScript snapshot has.
- `GeneratedSdk_PassesGoToolchainChecks` runs `go build ./...`, `go vet
./...` and `gofmt` on that SDK and asserts gofmt leaves the generated
top-level doc comments unchanged. go/printer only reformats doc comments
that start in column 1, so the indented interface-method and
struct-field comments are covered by the heading test above instead.
- `GoGeneratorEscapingTests` generates an SDK from hostile metadata: a
description of `Adds Foo.\nfunc init() {}\n// ` that tries to end the
comment and declare a function, capability ids, method, parameter and
property names containing double quotes, percent signs, backslashes,
hyphens and line separators, and exported values (a string, an enum
value and a dictionary key) containing an emoji. It checks the Verify
snapshot, that no injected statement appears in the output, and that the
output passes `go build` and `go vet`. With the escaping commit's
generator changes reverted, all three fail (the injected statement is in
the output, the snapshot differs and `go build` reports syntax errors).
With only the exported-value rendering reverted, the snapshot differs
and `go build` reports `escape is invalid Unicode code point U+D83D`.
The Go toolchain tests use the existing `[RequiresTools]` gate, like
`GeneratedTransport_SupportsDuplexCommunication`, so this PR adds no
test project, CI job or runtime dependency.
`eng/github-ci/test-trigger-map.yml` needs no entry: the moved file is a
linked `src/Shared` file, which the selector attributes to its consuming
projects, and the Python, Java and Rust generators and tests do not
reference it (see the `SelectTests` row below).
### Merging with the Go API reference exporter
#21195 adds the Go API reference exporter to the same project. At its
current head (`ec5022d3a9`) the two pull requests merge without textual
conflicts (checked with `git merge-tree`), but the exporter calls
`RenderGoExportedValueType`, which this change gives a required
`includeDocs` parameter, so whichever merges second needs a one-line
fix-up in `AtsGoCodeGenerator.ApiProjection.cs`: in
`ProjectExportedValues`, pass `includeDocs: false` to
`RenderGoExportedValueType`. The compiler flags that call.
`BuildNameMaps` builds the documentation maps itself, so the exporter's
`BuildApiModel` can render documentation without any change.
The exporter's `GoApiExportTests.GoOnlySurface` snapshot then shows the
ATS documentation summaries in place of the generated `X represents X.`
text. A trial merge of both heads with that fix-up built, and 80 of the
81 tests in the Go codegen test project passed. The one failure was that
snapshot, which differed only in those summaries and is re-accepted with
`dotnet verify accept -y`. That trial ran at earlier heads of both
branches (see Not verified).
### Merge with main
This branch merges main (`45de07f9e3`), which now contains #21188,
#21199 and #21261. The conflicts were in `AtsGoCodeGenerator.cs` and two
snapshots, and the resolution keeps both sides:
- Both sets of private fields and helpers are kept. `BuildNameMaps`
builds the accepting interfaces from #21199 first and the documentation
maps last, because the renderer resolves type names through the maps
built before it.
- The enum value constant takes its name from
`GetEnumMemberConstantName` (#21199), with this PR's value doc block and
string-literal escaping.
- DTO callback conversion keeps this PR's escaped map key together with
the updated `EmitGoCallbackShimBody` call from #21261.
- The union allowed-types note now also says that `float64` accepts any
built-in Go numeric type, matching the widened type switch from #21188.
The snapshots were regenerated, not merged by hand. In the two large
ones the non-comment, non-blank lines are identical to main's (see the
counts above).
## Validation
Run from the repository root on Windows after `restore.cmd`, with Go
1.27.0 installed so the `[RequiresTools]` tests ran and were not
skipped.
| Command | Exit | Result |
| --- | --- | --- |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.Go.Tests\Aspire.Hosting.CodeGeneration.Go.Tests.csproj
--no-launch-profile -- --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` | 0 | 79 passed, 0 failed, 0
skipped (65 on main) |
| `dotnet test --project
tests\Aspire.Hosting.CodeGeneration.TypeScript.Tests\Aspire.Hosting.CodeGeneration.TypeScript.Tests.csproj
--no-launch-profile -- --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` | 0 | 153 passed, 0 failed, 0
skipped (153 on main) |
| `dotnet run --project tools/SelectTests -- --from upstream/main --to
HEAD --explain` | 0 | 0 unattributed changed files, no fallback. Selects
7 of 100 PR test projects: `Aspire.Cli.EndToEnd.Tests`,
`Aspire.Cli.Tests`, `Aspire.Hosting.CodeGeneration.Go.Tests`,
`Aspire.Hosting.CodeGeneration.TypeScript.Tests`,
`Aspire.Hosting.Native.Core.Tests`, `Aspire.Hosting.RemoteHost.Tests`,
`Aspire.Managed.Tests`, and triggers the `cli-starter-validation`,
`extension-e2e`, `homebrew-installer`, `polyglot`,
`typescript-api-compat`, `typescript-sdk` and `winget-installer` PR
jobs. The Python, Java and Rust codegen test projects are not selected.
|
Not verified:
- The `polyglot` job and the full CI matrix. Of the selected test
projects, only the Go and TypeScript codegen projects and the code
generation classes of `Aspire.Hosting.RemoteHost.Tests`
(`CodeGenerationResolverTests`, `ApiReferenceExportTests` and
`ServiceErrorMessageTests`, 22 tests) were run locally. CI is the first
run for the rest.
- Whether the CI runners that run the Go test project have `go` on
`PATH`. The three toolchain tests depend on `[RequiresTools]`.
- That the generated SDK body is gofmt-clean. It is not clean on main
either, so only the comments are gofmt-checked.
- Generation time was measured once on a shared, busy machine, with main
and this change measured at different times.
- The checks that the new tests fail without each fix were run before
the two merges of main into this branch (`f06f16b7bf` and `45de07f9e3`)
and were not repeated.
- The Python, Java and Rust codegen test projects (29, 71 and 26 tests)
passed on an earlier head of this branch and were not re-run after the
exported-value and heading fixes. They do not link the moved shared file
or any file those fixes changed.
- The merge with #21195 was built and tested locally at its head
`7e3948ad85` and an earlier head of this branch only, in the Go codegen
test project and not in the full CI matrix. At its current head
`ec5022d3a9` only the textual merge was checked. #21195 may change
before it lands.
### Follow-up issues
- Escape ATS metadata in the shared scanner and the TypeScript, Python,
Java and Rust generators.
- Go SDK: package doc, standard generated-code header, gofmt-clean body,
LF output.
- Scanner: preserve `<para>` boundaries and code indentation.
- Go SDK: guard names derived with `ToCamelCase` (implementation names,
list and dictionary getter fields, builder and application
implementations) against Go keywords, and make `ReserveName` reject
keywords and predeclared names.
## Checklist
- Is this feature complete?
- [ ] Yes. Ready to ship.
- [x] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
- [x] Yes
- [ ] No
- Did you add public API?
- [ ] Yes
- If yes, did you have an API Review for it?
- [ ] Yes
- [ ] No
- Did you add `<remarks />` and `<code />` elements on your triple slash
comments?
- [ ] Yes
- [ ] No
- [x] No
- Does the change make any security assumptions or guarantees?
- [ ] Yes
- If yes, have you done a threat model and had a security review?
- [ ] Yes
- [ ] No
- [x] No
---------
Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
> [!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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
needs-area-labelAn area label is needed to ensure this gets routed to the appropriate area owners
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Merge order: no PR must land before this one. It overlaps #21197 in
AtsGoCodeGenerator.cs(private fields in the same block) andTwoPassScanningGeneratedAspire.verified.go. Whichever lands second keeps both sets of fields and re-accepts the snapshot withdotnet 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,
AddNodePoolon an AKS environment returnsAksNodePoolResource, andWithNodePooltakesKubernetesNodePoolResource:WithNodePoolis 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
Tthat at least one other concrete handle type derives from, the generator emits one small interface,AnyT, meaning "Tor anything derived fromT".AnyTreplacesTwhere the caller supplies a value:A type whose base type also has an accepting interface declares the base marker too, so an
AnyTvalue converts to theAnyinterface of each base type. From the 62-integration SDK described below:AnyTembedshandleReferenceand declares the unexported marker methodisT()plus the marker of each base type ofTthat has an accepting interface, sorted by name. The handle interface ofTand of every type derived fromTdeclares 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 anAnyAksPoolResourcepass it on to a parameter typedAnyPoolResource. No interface is embedded.AnyTis 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, sopool.WithPoolPeer(other)still returns the receiver's own type.AnyT, and user code cannot add to the family. The family is directional: anAnyAksPoolResourcevalue is accepted whereAnyPoolResourceis expected, anAnyPoolResourcevalue is still rejected whereAnyAksPoolResourceis 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 unexportedgetHandlemethod ofhandleReference, so this adds no new cross-package restriction.BuildAcceptingInterfacesinAtsGoCodeGenerator.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 existingReserveName, 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 eachAnyTforTand for each of its accepting base types, so it grows linearly with the SDK.Alternatives that were rejected:
Resourcemarker interface. This is the smallest change, but every builder satisfies it, so a wrong resource kind (for example a Foundry account passed toWithTool) is only rejected by the AppHost server at run time instead of at compile time.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.aspire.golinesaspire.gobytesTAnyTThe deterministic counts bound the cost to about 1% more compiler functions. On a 3-integration SDK (Kubernetes, AKS, Foundry)
aspire.gogrows 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
-benchtotal) 33.6 s and 23.1 s onmain, 28.9 s and 18.1 s with the change; code generation time (RPC) for the 64 packages 680 ms onmain, 644 ms with the change; median coldgo buildof the 3-integration SDK over 3 alternating runs 5.93 s onmain, 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:
WithNodePoolon 163 builders, and seven single-builder methods,WithTool,Unsubscribe,SetProperties,SetAuthProperties,SetConnection,SetSourceandResourceIdentifier. The last five take*Proxyhandle types (for exampleResourceIdentifier(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,AnyProjectResourceand 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,AnyJavaScriptAppResourceandAnyPythonAppResource). All three are among those seven, so no existing parameter changes, and passing anAnyTvalue on to anAnyBaseparameter is covered by the fixture and by a type-level probe (see Validation).Compatibility
TsatisfiesAnyT, because the interface ofTdeclares the marker. This covers all 170 parameter sites in the 62-integration SDK. Go does not convert[]T,map[string]Tor*Tto[]AnyT,map[string]AnyTor*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 toAnyT. No API in the 62-integration SDK has a slice, map or pointer parameter of such a type.aspire.Tand must also hold a derived builder usesaspire.AnyT.AnyTcarries 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 takeaspire.AnyAksPoolResourceand pass it on to an API that takesaspire.AnyPoolResource.Any*interface types.Known limitations
*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.*AnyT(it is*Tonmain). The generated runtime does not serialize a pointer to an interface as a handle (serializeValuepasses the pointer through unchanged), for*AnyTand for*Talike, 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.anywith a run-time check, and the check accepts derived builders.Not in this PR
IsInstanceOfTypeandIResourceBuilder<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.Tfor these parameters until the same rule is added there.Overlap with #21197
Both changes add private fields in the same block of
AtsGoCodeGenerator.csand both changeTwoPassScanningGeneratedAspire.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 withdotnet 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
mainat5ea175ce62. The two compile tests needgoonPATHand use the sameRequiresToolsgating as the existing generated-SDK compile test.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 generatordotnet 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"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 noAny*interface. If theAny*interfaces list only their own marker, the compile test fails instead withcannot 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,AksPoolResourcederived from it,SpotPoolResourcederived from that,GpuSpotPoolResourcederived 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 withgo build: one passes the derived builders where the base is expected, checks that fluent calls keep returning the receiver's own type, and passesAnyAksPoolResourceandAnySpotPoolResourcevalues on to parameters typed with theAnyinterface of the type itself and of each base type; the other asserts that exactly three errors are reported: a queue passed toWithPool, a base pool passed toWithAksPool, and anAnyPoolResourcevalue passed where anAnyAksPoolResourceis required. One of the six text tests scans the real hosting model and checks that theTestRedisResourcehandle, which derives fromContainerResource, declares and implements theAnyContainerResourcemarker. 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 satisfyAnyT.The only snapshot that changes is
TwoPassScanningGeneratedAspire.verified.go: 4Any*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 fourAny*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.jsonlistsAspire.Hosting.Kubernetes,Aspire.Hosting.Azure.KubernetesandAspire.Hosting.Foundryand setsfeatures.experimentalPolyglotGo, withASPIRE_REPO_ROOTpointing 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 declarestakesBicep(r aspire.AnyAzureBicepResource)andforward(r aspire.AnyAzureProvisioningResource) { takesBicep(r) }.mainaspire restore --apphost apphost.go --non-interactiveAny*interfacesAny*interfacesgo build ./probes/nodepool(AddNodePoolresult passed toWithNodePool)aspire.AksNodePoolResource does not implement aspire.KubernetesNodePoolResource (wrong type for method ExcludeFromManifest)go build ./probes/foundrytool(AI Search, Code Interpreter and Web Search tool builders passed toWithTool)go vet ./probes/nodepool,go vet ./probes/foundrytoolandgo vet ./probes/anyforward, each run separatelygo build ./probes/anyforward(anAnyAzureProvisioningResourcevalue passed on to a parameter typedAnyAzureBicepResource)Any*types)go build ./probes/foundryneg(a Foundry account passed toWithTool)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/anyforwardandgo vet ./probes/anyforwardboth exit 1 withaspire.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.
maingo build -gcflags=-e ./conv/...pg_certmanager, with identical errors on bothgo vet ./conv/...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.gofiles, and are not part of this PR.eng/github-ci/test-trigger-map.ymlneeds no change: the tests are in the existingAspire.Hosting.CodeGeneration.Go.Testsproject, and the generator is inAspire.Hosting.CodeGeneration.Go, which the map already routes to the polyglot job.Not run:
AnyTvalue on to anAnyBaseparameter. No API in the 62-integration SDK has that shape, so it is covered by the fixture and theanyforwardtype-level probe only.go 1.26).Checklist
<remarks />and<code />elements on your triple slash comments?