From a60467002177f3689871857cc7c53cf6ff4b49ad Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Tue, 10 Nov 2026 13:34:50 +0000 Subject: [PATCH 1/2] Update Go SDK option docs for idiomatic generated APIs --- .../docs/app-host/go-apphost-conventions.mdx | 22 +++++++++++-------- .../integrations/frameworks/go/go-host.mdx | 4 ++-- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx b/src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx index 9eb29923fc..e8350204a6 100644 --- a/src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx +++ b/src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx @@ -1,7 +1,7 @@ --- title: Go AppHost API conventions seoTitle: Go AppHost API conventions for the Aspire SDK -description: Learn how the generated Aspire Go SDK names methods, passes optional parameters with options structs, reports errors through handles, and cancels a running AppHost. +description: Learn how the generated Aspire Go SDK names methods, passes optional parameters with option values, reports errors through handles, and cancels a running AppHost. --- The Aspire CLI generates the Go SDK from the integrations in your `aspire.config.json` file, and every integration follows the same conventions. The examples on this page use a `builder` from `aspire.CreateBuilder()`, as in [Get started with the Go AppHost](/app-host/go-apphost/). @@ -14,19 +14,23 @@ Methods that add a resource, such as `AddRedis` and `AddGoApp`, return a _handle ## Optional parameters -Optional parameters go in a trailing variadic options argument. Leave it out to use the defaults. The argument is usually a struct named `Options`, such as `*aspire.WithHttpEndpointOptions`. Methods with the same name share one struct when their optional parameters match. If they don't match, or if another type already has the name, the name starts with the type that defines the method, such as `*aspire.ExecutableResourceWithVolumeOptions` for `WithVolume` on a Go app. A few methods take an existing type instead, such as `*aspire.DelveServerOptions` for `WithDelveServer`, and that type declares its own field types. - -In a `Options` struct, scalar fields (string, number, bool, and enum) are pointers, so a field that you don't set stays `nil`. Use `aspire.StringPtr`, `aspire.BoolPtr`, and `aspire.Float64Ptr` to create the values. Numeric fields are `*float64`. Slice, map, callback, and `any` fields can already be `nil`, so they aren't pointers. For example, `AddGoAppOptions.BuildTags` is a `[]string`. +Optional parameters go in a trailing variadic argument of option values. Leave it out to use the defaults. The argument type is `Option`, such as `aspire.WithHttpEndpointOption`. Each optional parameter has a typed value named ``, such as `aspire.HttpEndpointPort`, `aspire.HttpEndpointTargetPort`, and `aspire.HttpEndpointName`. Convert a literal to the typed value to set the parameter. You don't need pointer helpers or struct literals. ```go title="apphost.go" builder.AddGoApp("api", "./api"). - WithHttpEndpoint(&aspire.WithHttpEndpointOptions{ - Port: aspire.Float64Ptr(8080), - Env: aspire.StringPtr("PORT"), - }) + WithHttpEndpoint( + aspire.HttpEndpointPort(8080), + aspire.HttpEndpointName("http"), + ) ``` -The [`WithHttpEndpoint` API reference](/reference/api/go/aspire.hosting/withhttpendpoint/) describes each field of `WithHttpEndpointOptions`. +The `Option` interface is sealed, so only the generated option values satisfy it. A `*aspire.Options` struct, such as `*aspire.WithHttpEndpointOptions`, is still accepted as an option for source compatibility. In that struct, scalar fields (string, number, bool, and enum) are pointers, so a field that you don't set stays `nil`. `aspire.CreateBuilder` follows the same pattern with `aspire.CreateBuilderOption`. + +Numeric parameters use the Go type that matches the underlying .NET type, such as `int`, `int64`, `float32`, `float64`, or an unsigned type, instead of always using `float64`. Obsolete .NET members aren't generated, unless an active method signature still needs the type. + +Generated `.go` files are formatted with `gofmt`. + +The [`WithHttpEndpoint` API reference](/reference/api/go/aspire.hosting/withhttpendpoint/) describes each option of `WithHttpEndpoint`. ## Errors diff --git a/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx b/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx index 60a173d6f9..685cb70d9e 100644 --- a/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx +++ b/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx @@ -167,7 +167,7 @@ func main() { } api := builder.AddGoApp("api", "./api"). - WithHttpEndpoint(&aspire.WithHttpEndpointOptions{Port: aspire.Float64Ptr(8080), Env: aspire.StringPtr("PORT")}). + WithHttpEndpoint(aspire.HttpEndpointPort(8080), aspire.HttpEndpointEnv("PORT")). WithExternalHttpEndpoints() if err := api.Err(); err != nil { @@ -507,7 +507,7 @@ await builder.build().run(); ```go title="apphost.go" builder.AddGoApp("api", "./api"). WithDelveServer(). - WithHttpEndpoint(&aspire.WithHttpEndpointOptions{Port: aspire.Float64Ptr(8080), Env: aspire.StringPtr("PORT")}) + WithHttpEndpoint(aspire.HttpEndpointPort(8080), aspire.HttpEndpointEnv("PORT")) ``` From 263cb922084a3f873e3d5c21a162b42c09115d73 Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Tue, 17 Nov 2026 06:58:39 -0600 Subject: [PATCH 2/2] Describe typed Go option values in GoMemberCard Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../src/components/api-reference/GoMemberCard.astro | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/frontend/src/components/api-reference/GoMemberCard.astro b/src/frontend/src/components/api-reference/GoMemberCard.astro index a731747525..f09c58b10d 100644 --- a/src/frontend/src/components/api-reference/GoMemberCard.astro +++ b/src/frontend/src/components/api-reference/GoMemberCard.astro @@ -90,10 +90,13 @@ const parameters: { name: string; type: string; description?: string | null; isC })) : []; const options = isCallable ? member.options : undefined; +// Variadic options are typed values named , such as HttpEndpointPort. +const optionValuePrefix = member.name.replace(/^With(?=[A-Z])/, ''); +const optionInterfaceName = `Option`; if (options?.typeName) { parameters.push({ name: getGoOptionsParameterName({ signature: member.signature ?? undefined, options }), - type: `...*${options.typeName}`, + type: options.isDirect ? `...*${options.typeName}` : `...${optionInterfaceName}`, description: 'Optional settings, described under Options.', }); } @@ -183,8 +186,9 @@ const errorModelSegments = ) : (

Optional parameters are passed in a trailing{' '} - {getGoOptionsParameterName({ signature: member.signature ?? undefined, options })} ...*{options.typeName}{' '} - argument. + {getGoOptionsParameterName({ signature: member.signature ?? undefined, options })} ...{optionInterfaceName}{' '} + argument as typed option values, such as aspire.{optionValuePrefix}{optionFields[0]?.name ?? 'Option'}(value). The{' '} + *{options.typeName} struct is still accepted for compatibility.

)} {optionFields.length > 0 && (