Aspirerelease/17.0
Watch Aspire live streamsDokumentationPrøv Aspire

Go AppHost API conventions

Dette indhold er ikke tilgængeligt i dit sprog endnu.

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.

Every integration adds its methods to the aspire package, and method names are PascalCase. The TypeScript method addRedis is AddRedis in Go.

Numeric parameters and fields use the Go type that matches the .NET type, such as int for a port and int64 for a file size. Methods and properties that are marked obsolete in .NET aren’t generated.

Methods that add a resource, such as AddRedis and AddGoApp, return a handle. A handle is a Go interface that stands for the resource in the app model, for example aspire.RedisResource. Methods that configure a resource return the same handle type, so calls chain. Errors are reported when you call Build, as described in Errors.

Go interfaces don’t support covariant return types, so the handle for a derived resource type doesn’t satisfy the handle interface of its base type. When other resource types derive from a type, the SDK also generates an Any<Type> interface that accepts a handle of that type or of any type derived from it. Parameters that take such a resource use this interface. For example, WithNodePool takes an aspire.AnyKubernetesNodePoolResource, so it accepts the aspire.AksNodePoolResource handle that AddNodePool returns:

apphost.go
aks := builder.AddAzureKubernetesEnvironment("aks")
pool := aks.AddNodePool("workload", func(config *aspire.AksNodePoolConfig) {
config.MaxCount = 5
})
builder.AddContainer("api", "nginx").WithNodePool(pool)

The compiler rejects a handle of an unrelated resource type. Methods still return the receiver’s own handle type, so chained calls keep their type.

Optional parameters go in a trailing variadic options argument. Leave it out to use the defaults, or pass typed option values for the settings you want to change. You don’t need an options struct or pointer helpers:

apphost.go
builder.AddGoApp("api", "./api").
WithHttpEndpoint(aspire.HttpEndpointPort(8080), aspire.HttpEndpointEnv("PORT"))

Option names combine the method name without a leading With and the parameter name, such as HttpEndpointPort, HttpEndpointEnv, and AddGoAppPackagePath. Collection and callback options use the same pattern:

apphost.go
builder.AddGoApp("api", "./api",
aspire.AddGoAppPackagePath("./cmd/server"),
aspire.AddGoAppBuildTags([]string{"netgo", "integration"}),
aspire.AddGoAppRaceDetector(true),
)

Options are applied from left to right. Omitting an option preserves the default; passing false, 0, or "" explicitly sets that value. If you repeat an option, the last value wins.

The generated SDK still accepts pointer-based options structs for compatibility. DTO inputs that aren’t variadic options, such as AddContainerOptions, retain their declared field types. Check the generated SDK for the exact types and option names available for your installed integrations.

The WithHttpEndpoint API reference describes the available endpoint settings.

The SDK reports errors in two ways.

Methods that add or configure a resource return a handle instead of an error, so you can add many resources without checking each call. A failed resource doesn’t stop you from adding other resources. The SDK collects the error from every failed handle and Build returns them together, joined with errors.Join:

apphost.go
cache := builder.AddRedis("cache")
builder.AddGoApp("api", "./api").WithReference(cache)
app, err := builder.Build()
if err != nil {
log.Fatal(aspire.FormatError(err))
}

Each failure is reported once, even when it passes through a chain of calls. To check for errors before you call Build, call builder.Err(), which returns the same combined error. To check a single resource, call the Err() method on its handle, which returns the first error recorded for that resource.

Methods that return a value return a (T, error) pair, and Build and Run return an error:

apphost.go
dir, err := builder.AppHostDirectory()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
log.Println("AppHost directory:", dir)

aspire.FormatError turns an error into a message that is ready to log. When the AppHost server returns an error for a call, the error is an *aspire.CapabilityError, and FormatError adds its error code and the capability that failed. Use errors.As and the Code, Message, and Capability methods to read these values yourself. When the error combines several errors, such as the error that Build returns, FormatError formats each one on its own line. For any other error, FormatError returns err.Error().

If a callback that you pass to an SDK method panics, the AppHost process keeps running. The SDK recovers the panic and fails only the call that invoked the callback.

A method that accepts a cancellation token exposes a typed option for it, such as aspire.RunCancellationToken. Create a token with aspire.NewCancellationToken, pass it in the options, and call its Cancel method to cancel the call:

apphost.go
app, err := builder.Build()
if err != nil {
log.Fatal(aspire.FormatError(err))
}
// Cancel the Run call if the AppHost is still running after an hour.
token := aspire.NewCancellationToken()
time.AfterFunc(time.Hour, token.Cancel)
if err := app.Run(aspire.RunCancellationToken(token)); err != nil {
log.Fatal(aspire.FormatError(err))
}

You can’t create a token from a context.Context. To cancel a token when an existing context ends, call context.AfterFunc(ctx, token.Cancel). The token’s Context method returns a context.Context that ends when the token is canceled, so you can use the same token with other Go APIs.