From fcf75fb7a3fd22353bede79aab2ec782e4b45d64 Mon Sep 17 00:00:00 2001 From: David Fowler Date: Wed, 13 May 2026 21:43:44 -0700 Subject: [PATCH 1/5] Add first-class Go hosting docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/integrations/frameworks/go-apps.mdx | 412 ++++++++++++++---- 1 file changed, 333 insertions(+), 79 deletions(-) diff --git a/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx b/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx index 9e7fe67b6..df4a19963 100644 --- a/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx +++ b/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx @@ -1,97 +1,90 @@ --- title: Go integration -description: Learn how to use the Aspire Community Toolkit Go hosting integration to orchestrate Go applications alongside other resources in the Aspire app host. +description: Learn how to use the Aspire Go hosting integration to orchestrate Go applications in an Aspire solution. --- -import { Badge } from '@astrojs/starlight/components'; - -import { Image } from 'astro:assets'; +import { TabItem, Tabs } from '@astrojs/starlight/components'; import InstallPackage from '@components/InstallPackage.astro'; -import goIcon from '@assets/icons/go.svg'; - - - -Go logo -The Aspire Go hosting integration enables you to run Go applications alongside your other Aspire resources in the app host. Go apps participate in the same service discovery, health checks, OpenTelemetry export, and Aspire dashboard support as the rest of your solution. +The Aspire Go hosting integration enables you to run Go applications alongside your Aspire projects in the AppHost. The integration runs Go apps with the local Go toolchain, wires them into the Aspire app model, supports service discovery and endpoint configuration, and can generate publish-time Dockerfiles for deployment. + +:::caution[Community Toolkit package deprecated] +As of Aspire 13.4, Go hosting support is available in the official `Aspire.Hosting.Go` package. The previous `CommunityToolkit.Aspire.Hosting.Golang` package is deprecated because Go support has graduated into core Aspire. Use `Aspire.Hosting.Go` and `AddGoApp` / `addGoApp` for new Aspire 13.4+ applications. +::: -:::note -TypeScript AppHost support for this integration is not yet available. The examples on this page use the C# AppHost only. +:::note[Prerequisites] +Install the [Go toolchain](https://go.dev/dl/) and make sure the `go` command is available on your `PATH`. Install [Delve](https://github.com/go-delve/delve) and make sure the `dlv` command is available on your `PATH` when you use headless Delve debugging. ::: ## Hosting integration -To access the Go hosting APIs in your [`AppHost`](/get-started/app-host/) project, install the [📦 CommunityToolkit.Aspire.Hosting.Golang](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Golang) NuGet package: +To access the types and APIs for expressing Go resources in your [`AppHost`](/get-started/app-host/) project, install the [📦 Aspire.Hosting.Go](https://www.nuget.org/packages/Aspire.Hosting.Go) NuGet package: - + -### Add Go app +## Add Go app -Add a Go application to your app host using the `AddGolangApp` extension method: +Use `AddGoApp` / `addGoApp` to add a Go application to your AppHost. By default, Aspire runs `go run .` from the application directory. -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); + + -var goApp = builder.AddGolangApp("go-api", "../go-api") - .WithHttpEndpoint(env: "PORT") - .WithHttpHealthCheck("/health"); +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); -builder.AddProject("apiservice") - .WithReference(goApp); +var api = builder.AddGoApp("api", "./api") + .WithHttpEndpoint(port: 8080, env: "PORT") + .WithExternalHttpEndpoints(); builder.Build().Run(); ``` -`AddGolangApp` requires: + + -- **name**: The name of the resource in the Aspire dashboard. -- **workingDirectory**: The path to the directory containing your Go application, relative to the AppHost project. The app host runs `go run ` in this directory. +```typescript title="apphost.ts" +import { createBuilder } from './.modules/aspire.js'; -By default, the executable target is `.` (the Go module root), which is equivalent to `go run .`. +const builder = await createBuilder(); -### Specify the executable target +const api = await builder.addGoApp('api', './api'); +await api.withHttpEndpoint({ port: 8080, env: 'PORT' }); +await api.withExternalHttpEndpoints(); -Pass an explicit `executable` argument to run a package at a specific path inside the working directory: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var goApp = builder.AddGolangApp( - name: "go-api", - workingDirectory: "../go-api", - executable: "./cmd/server") - .WithHttpEndpoint(env: "PORT"); - -builder.Build().Run(); +await builder.build().run(); ``` -### Configure HTTP endpoints - -Go applications typically read the port from an environment variable. Use `WithHttpEndpoint` to declare the HTTP endpoint and bind it to a named environment variable: + + -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var goApp = builder.AddGolangApp("go-api", "../go-api") - .WithHttpEndpoint(port: 8080, env: "PORT"); +The method accepts the following common parameters: -builder.Build().Run(); -``` +- **name**: The name of the resource in the Aspire dashboard. +- **appDirectory**: The path to the Go module root. This directory usually contains `go.mod` and is also the Docker build context for `aspire publish`. +- **packagePath**: The Go package to run or build relative to `appDirectory`. Defaults to `"."`. -Your Go application reads the `PORT` variable at startup: +Go applications commonly read the `PORT` environment variable set by `WithHttpEndpoint` / `withHttpEndpoint`: -```go title="Go — main.go" +```go title="main.go" package main import ( "fmt" + "log" "net/http" "os" ) @@ -103,65 +96,326 @@ func main() { } http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { - fmt.Fprintf(w, "Hello from Go!") + fmt.Fprintln(w, "Hello from Go!") }) - fmt.Printf("Server listening on port %s\n", port) - http.ListenAndServe(":"+port, nil) + log.Printf("Listening on :%s", port) + log.Fatal(http.ListenAndServe(":"+port, nil)) } ``` -### Manage module dependencies +## Configure app directory and package path -Call `WithGoModTidy` to run `go mod tidy` before the Go app starts. This ensures the module's dependency graph is consistent and removes unused entries from `go.mod` and `go.sum`: +Use `appDirectory` for the Go module root, and use `packagePath` when the `main` package is under a subdirectory such as `cmd/server`. -```csharp title="C# — AppHost.cs" +For a common layout like this: + +```text title="Go app layout" +api/ +|-- go.mod +|-- internal/ +`-- cmd/ + `-- server/ + `-- main.go +``` + +Configure the AppHost to run `go run ./cmd/server` from `./api`: + + + + +```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var goApp = builder.AddGolangApp("go-api", "../go-api") - .WithGoModTidy() +var api = builder.AddGoApp( + name: "api", + appDirectory: "./api", + packagePath: "./cmd/server") .WithHttpEndpoint(env: "PORT"); builder.Build().Run(); ``` -Call `WithGoModDownload` to run `go mod download` instead. This downloads all module dependencies to the local module cache without modifying `go.mod` or `go.sum`: + + + +```typescript title="apphost.ts" +import { createBuilder } from './.modules/aspire.js'; + +const builder = await createBuilder(); + +const api = await builder.addGoApp('api', './api', { + packagePath: './cmd/server', +}); +await api.withHttpEndpoint({ env: 'PORT' }); + +await builder.build().run(); +``` + + + + +The same `packagePath` is used for local run mode, headless Delve debugging, and publish-time `go build`. + +## Configure build options + +Go build-time options are parameters on `AddGoApp` / `addGoApp`. Aspire passes them to `go run` during local development and to `go build` when it generates a Dockerfile for publish. + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var api = builder.AddGoApp( + name: "api", + appDirectory: "./api", + packagePath: "./cmd/server", + buildTags: ["netgo", "integration"], + ldFlags: "-X main.version=1.2.3 -s -w", + gcFlags: "all=-N -l", + raceDetector: true); + +builder.Build().Run(); +``` + + + + +```typescript title="apphost.ts" +import { createBuilder } from './.modules/aspire.js'; + +const builder = await createBuilder(); + +const api = await builder.addGoApp('api', './api', { + packagePath: './cmd/server', + buildTags: ['netgo', 'integration'], + ldFlags: '-X main.version=1.2.3 -s -w', + gcFlags: 'all=-N -l', + raceDetector: true, +}); + +await builder.build().run(); +``` + + + + +The options map to Go command-line flags: + +- `buildTags`: Adds `-tags=,`. +- `ldFlags`: Adds `-ldflags=`. +- `gcFlags`: Adds `-gcflags=`. +- `raceDetector`: Adds `-race` in local run mode. The generated Dockerfile excludes `-race` because race detection requires CGO and publish builds create a static Linux binary. + +## Pass app arguments + +Use `WithAppArgs` / `withAppArgs` to pass arguments to the Go program after the package path. -```csharp title="C# — AppHost.cs" + + + +```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var goApp = builder.AddGolangApp("go-api", "../go-api") - .WithGoModDownload() +var api = builder.AddGoApp("api", "./api") + .WithAppArgs("--config", "dev.yaml") .WithHttpEndpoint(env: "PORT"); builder.Build().Run(); ``` -Both methods run only in run mode and have no effect during publish. + + + +```typescript title="apphost.ts" +import { createBuilder } from './.modules/aspire.js'; + +const builder = await createBuilder(); + +const api = await builder.addGoApp('api', './api'); +await api.withAppArgs(['--config', 'dev.yaml']); +await api.withHttpEndpoint({ env: 'PORT' }); + +await builder.build().run(); +``` + + + -### Use build tags +In normal run mode, this produces a command like `go run . --config dev.yaml`. In headless Delve mode, Aspire passes the app arguments after Delve's `--` separator. -Pass `buildTags` to control conditional compilation in the Go source: +## Run Go module helper commands -```csharp title="C# — AppHost.cs" +The Go integration can run common module and static analysis commands before the app starts. These helpers create setup resources in run mode and make the Go app wait for them to complete. + + + + +```csharp title="AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); -var goApp = builder.AddGolangApp( - name: "go-api", - workingDirectory: "../go-api", - executable: ".", - buildTags: ["integration"]) +var api = builder.AddGoApp("api", "./api") + .WithModTidy() + .WithModVendor() + .WithModDownload() + .WithVetTool() .WithHttpEndpoint(env: "PORT"); builder.Build().Run(); ``` -The build tags are passed to `go run` as `-tags integration` and to the generated Dockerfile's build stage as `go build -tags integration`. + + + +```typescript title="apphost.ts" +import { createBuilder } from './.modules/aspire.js'; + +const builder = await createBuilder(); + +const api = await builder.addGoApp('api', './api'); +await api.withModTidy(); +await api.withModVendor(); +await api.withModDownload(); +await api.withVetTool(); +await api.withHttpEndpoint({ env: 'PORT' }); + +await builder.build().run(); +``` + + + + +The helper methods run these commands: + +- `WithModTidy` / `withModTidy`: Runs `go mod tidy -e`. +- `WithModVendor` / `withModVendor`: Runs `go mod vendor`. +- `WithModDownload` / `withModDownload`: Runs `go mod download`. +- `WithVetTool` / `withVetTool`: Runs `go vet ./...`. + +When multiple module helpers are configured, Aspire orders them so dependency-changing steps complete before later module cache or vendor steps. + +## Debug Go apps with Delve + +Go app resources enable VS Code Go debugging support by default. Install the [Go extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=golang.go), then use the normal Aspire debugging workflow. + +For GoLand, VS Code attach mode, or another Delve-compatible client, use `WithDelveServer` / `withDelveServer`. This replaces the application command with a headless Delve server, such as `dlv --headless=true --listen=127.0.0.1:2345 --api-version=2 debug .`. + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var api = builder.AddGoApp("api", "./api") + .WithDelveServer(port: 2345) + .WithHttpEndpoint(port: 8080, env: "PORT"); + +builder.Build().Run(); +``` + + + + +```typescript title="apphost.ts" +import { createBuilder } from './.modules/aspire.js'; + +const builder = await createBuilder(); + +const api = await builder.addGoApp('api', './api'); +await api.withDelveServer({ port: 2345 }); +await api.withHttpEndpoint({ port: 8080, env: 'PORT' }); + +await builder.build().run(); +``` + + + + +Start your attach configuration after the Go resource is running in the Aspire dashboard. For GoLand, create a **Go Remote** configuration with host `localhost` and port `2345`. For VS Code attach mode, add a launch configuration like this: + +```json title=".vscode/launch.json" +{ + "name": "Attach to api", + "type": "go", + "request": "attach", + "mode": "remote", + "host": "localhost", + "port": 2345 +} +``` + +## Publish Go apps + +When you run `aspire publish`, Aspire uses the `appDirectory` as the Docker build context: + +- If the app directory already contains a `Dockerfile`, Aspire uses it. +- If no `Dockerfile` exists, Aspire generates a multi-stage Dockerfile. +- The generated Dockerfile uses a `golang:-alpine` build image by default. Aspire detects the Go version from `go.mod`, preferring a `toolchain` directive over the `go` directive when both are present. +- The build stage runs `go mod download`, caches the module and build caches, and builds a static Linux binary with `CGO_ENABLED=0` and `GOOS=linux`. +- The runtime stage uses a small runtime image, installs certificate and time zone data for Alpine-based images, creates a non-root `app` user, and starts the compiled binary. +- The generated `go build` command uses the same `packagePath`, `buildTags`, `ldFlags`, and `gcFlags` configured on the Go app resource. It intentionally excludes `raceDetector` for publish builds. + +For private modules, use `WithGoPrivate` / `withGoPrivate` to configure the generated Dockerfile with `GOPRIVATE` and BuildKit secret-based authentication. This setting only affects generated Dockerfiles; local run mode continues to use the developer's local Go and Git credentials. + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var api = builder.AddGoApp("api", "./api") + .WithGoPrivate(["github.com/myorg"], "github.com"); + +builder.Build().Run(); +``` + + + + +```typescript title="apphost.ts" +import { createBuilder } from './.modules/aspire.js'; + +const builder = await createBuilder(); + +const api = await builder.addGoApp('api', './api'); +await api.withGoPrivate(['github.com/myorg'], 'github.com'); + +await builder.build().run(); +``` + + + + + + For more information about publishing Aspire apps, see [Deployment + overview](/deployment/overview/). + + +## Experimental Go AppHost templates + +The `Aspire.Hosting.Go` integration can be used from C# and TypeScript AppHosts. Aspire also includes experimental Go AppHost and Go starter template support in the Aspire CLI. The Go AppHost templates use experimental Go AppHost APIs instead of the `Aspire.Hosting.Go` package. To enable Go AppHost language support for CLI templates, enable the Go polyglot feature flag: + +```bash title="Aspire CLI" +aspire config set features:experimentalPolyglot:go true --global +``` + +After enabling the feature, you can create a Go starter app with: + +```bash title="Aspire CLI" +aspire new aspire-go-starter +``` + + + For more information about feature flags, see [Aspire CLI + configuration](/reference/cli/configuration/#toggle-preview-feature-experiences). + For template command details, see [`aspire + new`](/reference/cli/commands/aspire-new/). + ## See also -- [📦 CommunityToolkit.Aspire.Hosting.Golang](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Golang) - [Go documentation](https://go.dev/doc/) -- [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire) +- [Delve debugger](https://github.com/go-delve/delve) - [Aspire integrations overview](/integrations/overview/) - [Aspire GitHub repo](https://github.com/microsoft/aspire) From 99aa9462b635fe690b7ee3507d4299e592a22d07 Mon Sep 17 00:00:00 2001 From: David Fowler Date: Wed, 13 May 2026 23:07:56 -0700 Subject: [PATCH 2/5] Clarify Go publish artifact wording Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/integrations/frameworks/go-apps.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx b/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx index df4a19963..acd8e7161 100644 --- a/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx +++ b/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx @@ -347,7 +347,7 @@ Start your attach configuration after the Go resource is running in the Aspire d ## Publish Go apps -When you run `aspire publish`, Aspire uses the `appDirectory` as the Docker build context: +When a publisher or deployment target emits container build artifacts for a Go app, Aspire uses the `appDirectory` as the Docker build context: - If the app directory already contains a `Dockerfile`, Aspire uses it. - If no `Dockerfile` exists, Aspire generates a multi-stage Dockerfile. From 36e9184e8d721898edf63fca5819a7c56ba6e269 Mon Sep 17 00:00:00 2001 From: David Fowler Date: Thu, 14 May 2026 07:58:42 -0700 Subject: [PATCH 3/5] Restructure Go integration docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/frontend/config/redirects.mjs | 2 + .../config/sidebar/integrations.topics.ts | 17 +++- .../src/content/docs/community/thanks.mdx | 2 +- .../src/content/docs/get-started/app-host.mdx | 2 +- .../frameworks/go/go-get-started.mdx | 91 +++++++++++++++++++ .../{go-apps.mdx => go/go-host.mdx} | 91 ++++++++++++++----- .../content/docs/ja/get-started/app-host.mdx | 2 +- .../docs/languages-and-runtimes/index.mdx | 12 +-- .../src/data/aspire-integration-names.json | 3 +- src/frontend/src/data/integration-docs.json | 6 +- 10 files changed, 193 insertions(+), 35 deletions(-) create mode 100644 src/frontend/src/content/docs/integrations/frameworks/go/go-get-started.mdx rename src/frontend/src/content/docs/integrations/frameworks/{go-apps.mdx => go/go-host.mdx} (84%) diff --git a/src/frontend/config/redirects.mjs b/src/frontend/config/redirects.mjs index 9b81493da..6847c0bf0 100644 --- a/src/frontend/config/redirects.mjs +++ b/src/frontend/config/redirects.mjs @@ -174,6 +174,8 @@ export const redirects = { '/integrations/devtools/flagd/': '/integrations/devtools/flagd/flagd-get-started/', '/integrations/devtools/goff/': '/integrations/devtools/goff/goff-get-started/', '/integrations/devtools/mailpit/': '/integrations/devtools/mailpit/mailpit-get-started/', + '/integrations/frameworks/go/': '/integrations/frameworks/go/go-get-started/', + '/integrations/frameworks/go-apps/': '/integrations/frameworks/go/go-get-started/', '/integrations/frameworks/csharp-file-based-apps/': '/integrations/dotnet/csharp-file-based-apps/', '/integrations/frameworks/maui/': '/integrations/dotnet/maui/', '/fundamentals/service-defaults/': '/get-started/csharp-service-defaults/', diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 6a845b82b..7196d3b4c 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -1248,7 +1248,7 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { }, ], }, - { + { label: 'SQLite', collapsed: true, items: [ @@ -1338,7 +1338,20 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { ], }, { label: 'Dapr', slug: 'integrations/frameworks/dapr' }, - { label: 'Go', slug: 'integrations/frameworks/go-apps' }, + { + label: 'Go', + collapsed: true, + items: [ + { + label: 'Get started', + slug: 'integrations/frameworks/go/go-get-started', + }, + { + label: 'Set up Go apps in the AppHost', + slug: 'integrations/frameworks/go/go-host', + }, + ], + }, { label: 'Java', slug: 'integrations/frameworks/java' }, { label: 'JavaScript and Node.js', diff --git a/src/frontend/src/content/docs/community/thanks.mdx b/src/frontend/src/content/docs/community/thanks.mdx index d663c2560..a8a347445 100644 --- a/src/frontend/src/content/docs/community/thanks.mdx +++ b/src/frontend/src/content/docs/community/thanks.mdx @@ -803,7 +803,7 @@ Aspire speaks many languages — thanks to these communities. alongside Aspire.

- + Docs diff --git a/src/frontend/src/content/docs/get-started/app-host.mdx b/src/frontend/src/content/docs/get-started/app-host.mdx index f342579e6..7f0b5da07 100644 --- a/src/frontend/src/content/docs/get-started/app-host.mdx +++ b/src/frontend/src/content/docs/get-started/app-host.mdx @@ -109,7 +109,7 @@ architecture-beta This architecture demonstrates a **Go API** connecting to a **PostgreSQL database**, with a **React frontend** consuming the API. The Go API uses the standard library's `net/http` package or frameworks like Gin or Echo and connects to PostgreSQL using libraries like pgx or database/sql. The React frontend is built with Vite and communicates with the API over HTTP. diff --git a/src/frontend/src/content/docs/integrations/frameworks/go/go-get-started.mdx b/src/frontend/src/content/docs/integrations/frameworks/go/go-get-started.mdx new file mode 100644 index 000000000..fba14adb3 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/frameworks/go/go-get-started.mdx @@ -0,0 +1,91 @@ +--- +title: Get started with the Go integration +description: Understand how the Aspire Go hosting integration runs Go apps from your AppHost and how to choose the right setup path. +--- + +import { LinkButton, Steps } from '@astrojs/starlight/components'; +import ThemeImage from '@components/ThemeImage.astro'; +import goIcon from '@assets/icons/go-icon.png'; +import goLightIcon from '@assets/icons/go-light-icon.png'; + + + +The Aspire Go hosting integration lets you run Go applications alongside your other Aspire resources from the AppHost. Aspire runs Go apps with the local Go toolchain during development, wires them into the Aspire app model, supports service discovery and endpoint configuration, and can emit Dockerfile-based container build artifacts for deployment targets that need them. + +:::caution[Community Toolkit package deprecated] +As of Aspire 13.4, Go hosting support is available in the official `Aspire.Hosting.Go` package. The previous `CommunityToolkit.Aspire.Hosting.Golang` package is deprecated because Go support has graduated into core Aspire. Use `Aspire.Hosting.Go` and `AddGoApp` / `addGoApp` for new Aspire 13.4+ applications. +::: + +## Why use Go with Aspire + +Adding Go apps through Aspire gives you: + +- **One app model for every service.** Model Go applications, projects, containers, and backing services together in the AppHost. +- **Local development with the Go toolchain.** Aspire runs Go apps with commands such as `go run .` or `go run ./cmd/server` instead of requiring a container for every edit-run loop. +- **Endpoint and environment wiring.** Configure ports, environment variables, service discovery, and resource dependencies from the AppHost. +- **Dashboard visibility.** Go app resources appear in the Aspire dashboard with logs, status, endpoints, and lifecycle controls. +- **Publish-time container artifacts.** Deployment targets that need container build artifacts can use an existing Dockerfile or let Aspire generate one from the Go app resource. + +## How the pieces fit together + +The Go integration is a **hosting integration**. You install it in the AppHost, add one or more Go app resources, and configure how Aspire runs, debugs, and publishes each app. + +```mermaid +architecture-beta + + group apphost(server)[AppHost] + group goapp(server)[Go app] + + service hosting(server)[Go hosting integration] in apphost + service resource(logos:go)[Go app resource] in apphost + service toolchain(logos:go)[Go toolchain] in goapp + service app(logos:go)[Go process] in goapp + + hosting:R --> L:resource + resource:R --> L:toolchain + toolchain:R --> L:app +``` + + + +1. ### Set up Go apps in the AppHost + + Add the `Aspire.Hosting.Go` hosting integration to your AppHost, then use `AddGoApp` / `addGoApp` to model a Go app resource. The host reference covers package installation, common Go layouts, app arguments, build options, Go module helper commands, Delve debugging, private modules, and publish behavior. + + + Set up Go apps in the AppHost + + +2. ### Optionally try the Go AppHost templates + + The `Aspire.Hosting.Go` integration works from C# and TypeScript AppHosts. Aspire also includes experimental Go AppHost and Go starter template support in the Aspire CLI. These templates use experimental Go AppHost APIs instead of the `Aspire.Hosting.Go` package. + + + Try the experimental Go templates + + + + +## See also + +- [Go documentation](https://go.dev/doc/) +- [Go AppHost setup reference](/integrations/frameworks/go/go-host/) +- [Aspire integrations overview](/integrations/overview/) diff --git a/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx b/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx similarity index 84% rename from src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx rename to src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx index acd8e7161..5cac20497 100644 --- a/src/frontend/src/content/docs/integrations/frameworks/go-apps.mdx +++ b/src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx @@ -1,10 +1,9 @@ --- -title: Go integration -description: Learn how to use the Aspire Go hosting integration to orchestrate Go applications in an Aspire solution. +title: Set up Go apps in the AppHost +description: Learn how to use the Aspire Go hosting integration to orchestrate and configure Go applications in an Aspire solution. --- import { TabItem, Tabs } from '@astrojs/starlight/components'; -import InstallPackage from '@components/InstallPackage.astro'; import LearnMore from '@components/LearnMore.astro'; import ThemeImage from '@components/ThemeImage.astro'; import goIcon from '@assets/icons/go-icon.png'; @@ -20,7 +19,9 @@ import goLightIcon from '@assets/icons/go-light-icon.png'; classOverride="float-inline-left icon" /> -The Aspire Go hosting integration enables you to run Go applications alongside your Aspire projects in the AppHost. The integration runs Go apps with the local Go toolchain, wires them into the Aspire app model, supports service discovery and endpoint configuration, and can generate publish-time Dockerfiles for deployment. +This article is the reference for the Aspire Go hosting integration. It enumerates the AppHost APIs — with examples for both `AppHost.cs` and `apphost.ts` — that you use to orchestrate Go applications in your [`AppHost`](/get-started/app-host/) project. + +If you're new to the Go integration, start with the [Get started with the Go integration](/integrations/frameworks/go/go-get-started/) guide. :::caution[Community Toolkit package deprecated] As of Aspire 13.4, Go hosting support is available in the official `Aspire.Hosting.Go` package. The previous `CommunityToolkit.Aspire.Hosting.Golang` package is deprecated because Go support has graduated into core Aspire. Use `Aspire.Hosting.Go` and `AddGoApp` / `addGoApp` for new Aspire 13.4+ applications. @@ -30,11 +31,56 @@ As of Aspire 13.4, Go hosting support is available in the official `Aspire.Hosti Install the [Go toolchain](https://go.dev/dl/) and make sure the `go` command is available on your `PATH`. Install [Delve](https://github.com/go-delve/delve) and make sure the `dlv` command is available on your `PATH` when you use headless Delve debugging. ::: -## Hosting integration +## Installation + +To start building an Aspire app that uses Go, install the [📦 Aspire.Hosting.Go](https://www.nuget.org/packages/Aspire.Hosting.Go) NuGet package: + + + + +```bash title="Terminal" +aspire add go +``` + + + Learn more about [`aspire add`](/reference/cli/commands/aspire-add/) in the + command reference. + + +Or, choose a manual installation approach: + +```csharp title="C# — AppHost.cs" +#:package Aspire.Hosting.Go@* +``` + +```xml title="XML — AppHost.csproj" + +``` + + + + +```bash title="Terminal" +aspire add go +``` + + + Learn more about [`aspire add`](/reference/cli/commands/aspire-add/) in the + command reference. + -To access the types and APIs for expressing Go resources in your [`AppHost`](/get-started/app-host/) project, install the [📦 Aspire.Hosting.Go](https://www.nuget.org/packages/Aspire.Hosting.Go) NuGet package: +This updates your `aspire.config.json` with the Go hosting integration package: - +```json title="aspire.config.json" ins={3} +{ + "packages": { + "Aspire.Hosting.Go": "13.4.0" + } +} +``` + + + ## Add Go app @@ -43,7 +89,7 @@ Use `AddGoApp` / `addGoApp` to add a Go application to your AppHost. By default, -```csharp title="AppHost.cs" +```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var api = builder.AddGoApp("api", "./api") @@ -56,7 +102,7 @@ builder.Build().Run(); -```typescript title="apphost.ts" +```typescript title="TypeScript — apphost.ts" import { createBuilder } from './.modules/aspire.js'; const builder = await createBuilder(); @@ -74,7 +120,7 @@ await builder.build().run(); The method accepts the following common parameters: - **name**: The name of the resource in the Aspire dashboard. -- **appDirectory**: The path to the Go module root. This directory usually contains `go.mod` and is also the Docker build context for `aspire publish`. +- **appDirectory**: The path to the Go module root. This directory usually contains `go.mod` and is also the Docker build context for deployment targets that emit container build artifacts. - **packagePath**: The Go package to run or build relative to `appDirectory`. Defaults to `"."`. Go applications commonly read the `PORT` environment variable set by `WithHttpEndpoint` / `withHttpEndpoint`: @@ -124,7 +170,7 @@ Configure the AppHost to run `go run ./cmd/server` from `./api`: -```csharp title="AppHost.cs" +```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var api = builder.AddGoApp( @@ -139,7 +185,7 @@ builder.Build().Run(); -```typescript title="apphost.ts" +```typescript title="TypeScript — apphost.ts" import { createBuilder } from './.modules/aspire.js'; const builder = await createBuilder(); @@ -164,7 +210,7 @@ Go build-time options are parameters on `AddGoApp` / `addGoApp`. Aspire passes t -```csharp title="AppHost.cs" +```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var api = builder.AddGoApp( @@ -182,7 +228,7 @@ builder.Build().Run(); -```typescript title="apphost.ts" +```typescript title="TypeScript — apphost.ts" import { createBuilder } from './.modules/aspire.js'; const builder = await createBuilder(); @@ -215,7 +261,7 @@ Use `WithAppArgs` / `withAppArgs` to pass arguments to the Go program after the -```csharp title="AppHost.cs" +```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var api = builder.AddGoApp("api", "./api") @@ -228,7 +274,7 @@ builder.Build().Run(); -```typescript title="apphost.ts" +```typescript title="TypeScript — apphost.ts" import { createBuilder } from './.modules/aspire.js'; const builder = await createBuilder(); @@ -252,7 +298,7 @@ The Go integration can run common module and static analysis commands before the -```csharp title="AppHost.cs" +```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var api = builder.AddGoApp("api", "./api") @@ -268,7 +314,7 @@ builder.Build().Run(); -```typescript title="apphost.ts" +```typescript title="TypeScript — apphost.ts" import { createBuilder } from './.modules/aspire.js'; const builder = await createBuilder(); @@ -304,7 +350,7 @@ For GoLand, VS Code attach mode, or another Delve-compatible client, use `WithDe -```csharp title="AppHost.cs" +```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var api = builder.AddGoApp("api", "./api") @@ -317,7 +363,7 @@ builder.Build().Run(); -```typescript title="apphost.ts" +```typescript title="TypeScript — apphost.ts" import { createBuilder } from './.modules/aspire.js'; const builder = await createBuilder(); @@ -361,7 +407,7 @@ For private modules, use `WithGoPrivate` / `withGoPrivate` to configure the gene -```csharp title="AppHost.cs" +```csharp title="C# — AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); var api = builder.AddGoApp("api", "./api") @@ -373,7 +419,7 @@ builder.Build().Run(); -```typescript title="apphost.ts" +```typescript title="TypeScript — apphost.ts" import { createBuilder } from './.modules/aspire.js'; const builder = await createBuilder(); @@ -417,5 +463,6 @@ aspire new aspire-go-starter - [Go documentation](https://go.dev/doc/) - [Delve debugger](https://github.com/go-delve/delve) +- [Get started with the Go integration](/integrations/frameworks/go/go-get-started/) - [Aspire integrations overview](/integrations/overview/) - [Aspire GitHub repo](https://github.com/microsoft/aspire) diff --git a/src/frontend/src/content/docs/ja/get-started/app-host.mdx b/src/frontend/src/content/docs/ja/get-started/app-host.mdx index fe6ac31c0..05fd87c42 100644 --- a/src/frontend/src/content/docs/ja/get-started/app-host.mdx +++ b/src/frontend/src/content/docs/ja/get-started/app-host.mdx @@ -109,7 +109,7 @@ architecture-beta このアーキテクチャは、**Go API** が **PostgreSQL データベース**に接続し、**React フロントエンド**がその API を利用する構成を示しています。Go API は標準ライブラリの `net/http` パッケージ、または Gin や Echo などのフレームワークを使用し、pgx や database/sql などのライブラリを用いて PostgreSQL に接続します。React フロントエンドは Vite で構築され、HTTP 経由で API と通信します。 diff --git a/src/frontend/src/content/docs/languages-and-runtimes/index.mdx b/src/frontend/src/content/docs/languages-and-runtimes/index.mdx index d9be3b222..699653564 100644 --- a/src/frontend/src/content/docs/languages-and-runtimes/index.mdx +++ b/src/frontend/src/content/docs/languages-and-runtimes/index.mdx @@ -62,17 +62,17 @@ The sections below use the labels that are most helpful when you're trying to an Start with [Python integration](/integrations/frameworks/python/) and [Standalone Aspire dashboard for Python](/dashboard/standalone-for-python/). - - -### Community Toolkit guides - - Add Go services through the Community Toolkit. + Use Aspire with Go services and the local Go toolchain. - Start with [Go integration](/integrations/frameworks/go-apps/). + Start with [Go integration](/integrations/frameworks/go/go-get-started/). + + +### Community Toolkit guides + Add Java services through the Community Toolkit. diff --git a/src/frontend/src/data/aspire-integration-names.json b/src/frontend/src/data/aspire-integration-names.json index 098d801bf..1b19fbcf1 100644 --- a/src/frontend/src/data/aspire-integration-names.json +++ b/src/frontend/src/data/aspire-integration-names.json @@ -40,6 +40,7 @@ "Aspire.Hosting.Elasticsearch", "Aspire.Hosting.Garnet", "Aspire.Hosting.GitHub.Models", + "Aspire.Hosting.Go", "Aspire.Hosting.JavaScript", "Aspire.Hosting.Kafka", "Aspire.Hosting.Keycloak", @@ -137,4 +138,4 @@ "CommunityToolkit.Aspire.OllamaSharp", "CommunityToolkit.Aspire.RavenDB.Client", "CommunityToolkit.Aspire.SurrealDb" -] \ No newline at end of file +] diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index b6cb5330d..8e1aa57bd 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -179,6 +179,10 @@ "match": "Aspire.Hosting.GitHub.Models", "href": "/integrations/ai/github-models/github-models-get-started/" }, + { + "match": "Aspire.Hosting.Go", + "href": "/integrations/frameworks/go/go-get-started/" + }, { "match": "Aspire.Hosting.JavaScript", "href": "/integrations/frameworks/javascript/" @@ -409,7 +413,7 @@ }, { "match": "CommunityToolkit.Aspire.Hosting.Golang", - "href": "/integrations/frameworks/go-apps/" + "href": "/integrations/frameworks/go/go-get-started/" }, { "match": "CommunityToolkit.Aspire.Hosting.Java", From 5a0d5cc33a5cafa784365b8b5f6b943952a6d710 Mon Sep 17 00:00:00 2001 From: David Fowler Date: Thu, 14 May 2026 09:53:54 -0700 Subject: [PATCH 4/5] Allow known Foundry twoslash gap Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/frontend/tests/unit/twoslash-blocks-audit.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/frontend/tests/unit/twoslash-blocks-audit.ts b/src/frontend/tests/unit/twoslash-blocks-audit.ts index 4d7ebd5bd..54b7fb835 100644 --- a/src/frontend/tests/unit/twoslash-blocks-audit.ts +++ b/src/frontend/tests/unit/twoslash-blocks-audit.ts @@ -219,6 +219,15 @@ export const KNOWN_TYPE_BUGS: ReadonlyArray = [ messageContains: "'\"openai/gpt-4o-mini\"' is not assignable to parameter of type 'GitHubModelName'", label: 'GitHubModelName literal union outdated', }, + + // 5. Foundry role-assignment helper missing from generated TypeScript declarations + { + page: 'integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx', + blockIndex: 9, + code: 2551, + messageContains: "Property 'withFoundryRoleAssignments' does not exist on type 'ProjectResource'", + label: 'withFoundryRoleAssignments missing', + }, ]; /** Match a diagnostic against the allowlist. */ From 0b69ac40f7dfa90ad377643342dcef2b4cdd13fd Mon Sep 17 00:00:00 2001 From: David Fowler Date: Thu, 14 May 2026 13:18:35 -0700 Subject: [PATCH 5/5] Exclude deprecated Go toolkit package Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/frontend/scripts/update-integrations.ts | 1 + src/frontend/src/data/integration-docs.json | 4 ---- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/src/frontend/scripts/update-integrations.ts b/src/frontend/scripts/update-integrations.ts index 5ff35f5dc..743dcb9f8 100644 --- a/src/frontend/scripts/update-integrations.ts +++ b/src/frontend/scripts/update-integrations.ts @@ -21,6 +21,7 @@ const EXCLUDED_PACKAGES = [ 'Aspire.RabbitMQ.Client.v7', 'CommunityToolkit.Aspire.Hosting.Azure.StaticWebApps', 'CommunityToolkit.Aspire.Hosting.EventStore', + 'CommunityToolkit.Aspire.Hosting.Golang', 'CommunityToolkit.Aspire.EventStore', ]; const OUTPUT_PATH = './src/data/aspire-integrations.json'; diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 8e1aa57bd..1905ae9c6 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -411,10 +411,6 @@ "match": "CommunityToolkit.Aspire.Hosting.GoFeatureFlag", "href": "/integrations/devtools/goff/" }, - { - "match": "CommunityToolkit.Aspire.Hosting.Golang", - "href": "/integrations/frameworks/go/go-get-started/" - }, { "match": "CommunityToolkit.Aspire.Hosting.Java", "href": "/integrations/frameworks/java/"