Get started with the Go AppHost
このコンテンツはまだ日本語訳がありません。
A Go AppHost is a Go program that defines the resources in your application and how they connect. It uses the same app model as a C# AppHost, through a Go SDK that the Aspire CLI generates from the hosting integrations you install.
Prerequisites
Section titled “Prerequisites”- Go 1.26 or later, with
goon yourPATH - The Aspire CLI
- Node.js for the starter template’s React frontend
- A container runtime if you include the optional Redis cache in the starter template. See Aspire prerequisites for the supported options.
Create a Go AppHost
Section titled “Create a Go AppHost”Create a new app from the Go starter template:
aspire new aspire-go-starter -n aspire-app -o aspire-appThe template creates a Go AppHost (apphost.go), a Go API (api/), a Vite and React frontend (frontend/), and the generated SDK. The frontend waits for the API and proxies /api requests to it, and it loads /api/weatherforecast on startup. When you publish, the frontend build output is copied into the Go API container and served from ./static, so the deployed app uses one origin. Redis is optional: aspire new prompts for it interactively (default yes), and non-interactive runs omit it unless you pass --use-redis-cache true. To choose from the templates that support Go, run aspire new --language go instead.
See the aspire new command reference for all options.
The project has the following structure:
ディレクトリaspire-app/
ディレクトリ.aspire/modules/ Generated Go SDK (do not edit)
- aspire.go
- base.go
- go.mod
- transport.go
ディレクトリ.vscode/
- extensions.json Recommended VS Code extensions
ディレクトリapi/ Go API that the AppHost runs
- go.mod
- main.go
- telemetry.go
ディレクトリfrontend/ Vite and React frontend
ディレクトリpublic/
- …
ディレクトリsrc/
- …
- index.html
- package.json
- package-lock.json
- vite.config.ts
- …
- .gitignore Keeps the generated .aspire/ directory out of source control
- apphost.go Your AppHost entry point
- aspire.config.json Aspire configuration
- go.mod Go module for the AppHost
Run the AppHost
Section titled “Run the AppHost”From the project directory, start the AppHost with the Aspire CLI:
aspire runThe CLI regenerates the SDK when the packages list has changed, starts the AppHost with go run ., and prints the dashboard URL. Open the dashboard to see the app Go API and frontend resources with their logs, traces, and metrics. If you included Redis, the dashboard also shows the cache resource. Open the frontend endpoint to use the React app.
apphost.go
Section titled “apphost.go”The AppHost is a package main Go program. The following example shows the starter with Redis enabled. It defines a Go API, a Vite frontend that references and waits for the API, and a Redis cache:
package main
import ( "log"
"apphost/modules/aspire")
func main() { builder, err := aspire.CreateBuilder() if err != nil { log.Fatal(aspire.FormatError(err)) }
// A Redis cache the API will use for read-through caching. cache := builder.AddRedis("cache")
// Keep Go modules current and send traces, metrics, and logs to the dashboard. api := builder.AddGoApp("app", "./api"). WithModTidy(). WithReference(cache). WaitFor(cache). WithHttpEndpoint(aspire.HttpEndpointEnv("PORT")). WithHttpHealthCheck(aspire.HttpHealthCheckPath("/health")). WithExternalHttpEndpoints(). WithOtlpExporter()
// Reference the app for Vite proxying and wait until it is healthy. frontend := builder.AddViteApp("frontend", "./frontend"). WithReference(api). WaitFor(api)
// Bundle the frontend into the app container for same-origin production serving. api.PublishWithContainerFiles(frontend, "./static")
application, err := builder.Build() if err != nil { log.Fatal(aspire.FormatError(err)) } if err := application.Run(); err != nil { log.Fatal(aspire.FormatError(err)) }}PublishWithContainerFiles copies the frontend build output into the Go API container at ./static when you publish. The API serves those files from the same origin as its API endpoints.
If you omit Redis, the generated AppHost has no AddRedis call, WithReference(cache), or WaitFor(cache). The frontend and publish configuration stay the same.
The program has three parts:
aspire.CreateBuilder()connects to the AppHost server that the CLI starts and returns the builder.AddGoApp,AddViteApp, and the optionalAddRedisadd resources. Each call returns a handle, soWithReference,WaitFor, and the other configuration methods chain onto it.builder.Build()creates the application, andapplication.Run()blocks until the AppHost stops. Both return an error. You don’t check each resource: errors from theAddandWithcalls are collected and reported together when you callBuild. See Go AppHost API conventions for how errors are reported and formatted.
See Deploy Go apps for publishing and deployment options.
aspire.config.json
Section titled “aspire.config.json”The aspire.config.json file is the central configuration for your AppHost. This example includes the optional Redis integration:
{ "appHost": { "path": "apphost.go", "language": "go" }, "packages": { "Aspire.Hosting.Go": "17.0.0", "Aspire.Hosting.JavaScript": "17.0.0", "Aspire.Hosting.Redis": "17.0.0" }, "profiles": { "https": { "applicationUrl": "https://localhost:17127;http://localhost:15118", "environmentVariables": { "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21169", "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22260" } }, "http": { "applicationUrl": "http://localhost:15118", "environmentVariables": { "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19001", "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20115", "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true" } } }}If you omit Redis, the packages section contains only Aspire.Hosting.Go and Aspire.Hosting.JavaScript.
Key sections
Section titled “Key sections”| Section | Description |
|---|---|
appHost.path | Path to the AppHost entry point (apphost.go) |
appHost.language | The AppHost language (go) |
packages | Hosting integration packages and their versions. aspire add updates this section. |
profiles | Launch profiles with dashboard URLs and environment variables |
Generated SDK
Section titled “Generated SDK”The .aspire/modules/ directory holds the Go SDK that the CLI generates from the packages in aspire.config.json. The CLI creates and updates it, so don’t edit these files.
| File | Purpose |
|---|---|
aspire.go | Typed API for the installed integrations |
base.go | Handle, option, and error infrastructure |
transport.go | JSON-RPC transport to the AppHost server |
The SDK is one Go package for all integrations. The AppHost’s go.mod file maps the apphost/modules/aspire import path to the .aspire/modules/ directory, so apphost.go imports it like any other package:
module apphost
go 1.26
require apphost/modules/aspire v0.0.0
replace apphost/modules/aspire => ./.aspire/modulesThe SDK regenerates when:
- You run
aspire addto add or update an integration - You run
aspire runoraspire startand the package list has changed - You run
aspire restore
Documentation in the SDK
Section titled “Documentation in the SDK”The generated aspire.go includes godoc comments, so go doc and editor hover (gopls) show each API’s summary, parameters, and return value. Obsolete APIs carry a Deprecated: notice that gopls and staticcheck flag, and experimental APIs are marked with an Experimental heading.
Restore the SDK
Section titled “Restore the SDK”Run aspire restore to regenerate the SDK without starting the AppHost:
aspire restore --apphost apphost.goRestore after you clone a repository, switch branches, or edit the packages section by hand. In CI, restore before any step that compiles the AppHost, such as go build or go vet.
Add integrations
Section titled “Add integrations”Use aspire add from the AppHost directory to add a hosting integration. The CLI adds the package to aspire.config.json and regenerates the Go SDK in .aspire/modules/:
aspire add postgresqlThe packages section now lists the PostgreSQL integration:
{ "packages": { "Aspire.Hosting.Go": "17.0.0", "Aspire.Hosting.JavaScript": "17.0.0", "Aspire.Hosting.Redis": "17.0.0", "Aspire.Hosting.PostgreSQL": "17.0.0" }}The regenerated SDK has an AddPostgres method. This AppHost adds a PostgreSQL server with one database and gives the API access to it, retaining the starter’s frontend and publish configuration. As in the previous example, omit the Redis package and cache configuration if you didn’t include Redis:
package main
import ( "log"
"apphost/modules/aspire")
func main() { builder, err := aspire.CreateBuilder() if err != nil { log.Fatal(aspire.FormatError(err)) }
cache := builder.AddRedis("cache") db := builder.AddPostgres("postgres").AddDatabase("postgresdb")
api := builder.AddGoApp("app", "./api"). WithModTidy(). WithReference(cache). WithReference(db). WaitFor(cache). WaitFor(db). WithHttpEndpoint(aspire.HttpEndpointEnv("PORT")). WithExternalHttpEndpoints(). WithOtlpExporter()
frontend := builder.AddViteApp("frontend", "./frontend"). WithReference(api). WaitFor(api)
api.PublishWithContainerFiles(frontend, "./static")
app, err := builder.Build() if err != nil { log.Fatal(aspire.FormatError(err)) } if err := app.Run(); err != nil { log.Fatal(aspire.FormatError(err)) }}AddPostgresadds the PostgreSQL server, andAddDatabasereturns a handle for a database on that server.WithReference(db)passes the connection details to the API as environment variables named after the resource, such asPOSTGRESDB_URI. See Connect to PostgreSQL for a Go example that reads them.WaitFor(db)starts the API after the database is ready.- Any error from these calls is reported when you call
Build.
Orchestrate apps in other languages
Section titled “Orchestrate apps in other languages”A Go AppHost can run resources written in other languages next to your Go apps. Add the integration for each language that you use. Python and Node.js must also be installed, because these resources run on your machine:
aspire add pythonaspire add javascriptThis AppHost runs a Go API and a Python recommendation service that share a Redis cache, and a Vite frontend that calls both:
package main
import ( "log"
"apphost/modules/aspire")
func main() { builder, err := aspire.CreateBuilder() if err != nil { log.Fatal(aspire.FormatError(err)) }
cache := builder.AddRedis("cache")
api := builder.AddGoApp("api", "./api"). WithReference(cache). WaitFor(cache). WithHttpEndpoint(aspire.HttpEndpointEnv("PORT"))
recommender := builder.AddUvicornApp("recommender", "./recommender", "main:app"). WithReference(cache). WaitFor(cache)
builder.AddViteApp("web", "./web"). WithReference(api). WithReference(recommender). WaitFor(api)
app, err := builder.Build() if err != nil { log.Fatal(aspire.FormatError(err)) } if err := app.Run(); err != nil { log.Fatal(aspire.FormatError(err)) }}AddUvicornAppruns a Python ASGI app. Themain:appargument names the Python module and the application object in it.AddViteAppruns a Vite frontend.AddUvicornAppandAddViteAppalready register anhttpendpoint that reads its port fromPORT, so only the Go API callsWithHttpEndpoint.WithReferenceandWaitForwork the same for every resource type. The frontend receives the endpoints of the API and the recommender, and it starts after the API is ready.
See Set up JavaScript apps in the AppHost and Python integration for the options of each integration.
Debug a Go AppHost
Section titled “Debug a Go AppHost”To debug AppHosts and their resources in Visual Studio Code, see Run, debug, and deploy.