# Go AppHost API conventions

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/).

## Names and handles

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](#errors).

### Pass derived resource handles

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:

```go title="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

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:

```go title="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:

```go title="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](/reference/api/go/aspire.hosting/withhttpendpoint/) describes the available endpoint settings.

## Errors

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

```go title="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`:

```go title="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.

## Cancellation

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:

```go title="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.

## See also

- [Get started with the Go AppHost](/app-host/go-apphost/)
- [Go API reference](/reference/api/go/)