Document the Go AppHost: getting started, conventions and CLI references by IEvangelist · Pull Request #1924 · microsoft/aspire.dev

David Pine (IEvangelist) · 2026-10-20T05:59:16Z

Important

Depends on:

Make new Go AppHosts gofmt-clean, ignore the generated SDK and check every resource aspire#21193: go-apphost.mdx shows what aspire new aspire-go-starter writes, and the .gitignore that lists .aspire/ and the handle checks in the apphost.go fence come from that PR. Merge this PR after it.
Add Go API reference #1917: links to /reference/api/go/ resolve only once the Go API reference is on release/17.0.
Remove the Go AppHost experimental feature flag aspire#21183: these pages document Go without a feature flag, but the CLI still requires the flag until that PR merges. The pages go live at the GA docs swap, after the flag is removed.

Summary

Adds Go AppHost documentation next to the existing C# and TypeScript pages. This is the docs and samples child (microsoft/aspire#21112) of Go AppHost GA (microsoft/aspire#21115). The content goes live at the GA docs swap, because it targets release/17.0.

New pages, each with its sidebar entry in the same commit:

app-host/go-apphost: getting started. Prerequisites, creating a Go AppHost with aspire new and aspire init, running it, the apphost.go and aspire.config.json layout, the generated SDK and restore, adding integrations, orchestrating apps in other languages, and debugging.
app-host/go-apphost-conventions: how the Go API differs from C#: names and handles, optional parameters, the error model, and cancellation.

Edited pages:

languages-and-runtimes/index.mdx and architecture/multi-language-architecture.mdx: Go is listed and explained next to TypeScript.
integrations/frameworks/go/go-host.mdx and go-get-started.mdx: go-host.mdx gets Go AppHost examples in tab groups beside the C# and TypeScript ones, and its "Experimental Go AppHost templates" section becomes "Write the AppHost in Go". go-get-started.mdx points to the new getting started page. Nothing else links to the old anchor.
reference/cli/commands/aspire-new.mdx, aspire-add.mdx, aspire-restore.mdx and aspire-init.mdx: the Go templates, --language go, and how Go AppHosts are added to and restored.
reference/cli/configuration.mdx and reference/cli/includes/config-settings-table.md: the Go feature flag row is removed from the settings table, and the examples that used it now use the Rust flag, because the Go AppHost doesn't require a flag at GA.

Notes for reviewers:

The Go AppHost doesn't require a feature flag at GA ([Go AppHost GA] Remove the feature flag and expose Go templates aspire#21106), so the pages document none: go-apphost.mdx has no flag caution, and the Go row is gone from the CLI configuration reference. The CLI still requires the flag until Remove the Go AppHost experimental feature flag aspire#21183 removes it.
go-apphost.mdx shows what aspire new aspire-go-starter writes. The .gitignore that lists .aspire/ and the handle checks in the apphost.go fence come from Make new Go AppHosts gofmt-clean, ignore the generated SDK and check every resource aspire#21193, so merge this PR after it.
Links to /reference/api/go/ resolve only once the Go API reference (Add Go API reference #1917) is on release/17.0, because the link validator skips /reference/api/**.
Not in this PR, and tracked as follow-ups: Go tabs on the other pages that have a TypeScript tab and no Go tab (1,030 tab groups in 173 files when audited), Go in the site's AppHost-language pivot, which knows only C# and TypeScript (AppHost-language selector: teach the docs site about Go #1926), and the Java, Python and Rust rows in the CLI configuration reference, which still use the older experimentalPolyglot:<lang> colon spelling instead of the flat keys the CLI reads on main (CLI configuration reference: use the flat experimentalPolyglot keys #1925).

Third-party links and affiliations

One link: https://go.dev/dl/, the official Go download page, in the prerequisites of go-apphost.mdx. The author has no material affiliation with the Go project. The loopback URLs in the aspire.config.json sample are example values, not links.

Validation

The frontend commands ran in src/frontend.

Command	Result
`pnpm lint`	exit 0, ESLint `--max-warnings 0` clean, skill digests up to date
`pnpm test:unit`	exit 0, 84 test files passed, 1169 tests passed, 1 skipped, 0 failed
`bash tests/scripts/test-forbidden-words.sh`	passed
`bash .github/scripts/check-forbidden-words.sh 5c48cfbd9c54af9b05a58bb71a85a577e78b9339 e961e1efb8a2eab8dff213c5f85e307ecf9733f5`	exit 0, "No forbidden phrases found in added lines."
`git diff --check upstream/release/17.0...HEAD`	exit 0, no output
`go build -o NUL ./fences/...` and `go vet ./fences/...`	both exit 0 for the 16 added Go fences and 1 existing one (17 packages, Go 1.27.0), extracted from the page text and built against a real generated SDK

Forbidden words: run locally with an LF-writing jq, because the Windows jq writes CRLF and made the first local run pass vacuously. CI is the authority.
Rendering: all 11 new and edited pages return 200 on a local dev server that includes Add Go API reference #1917, with their new content. The 19 distinct internal links and 3 anchors added here resolve, including the Go API reference routes.
CLI behavior: aspire init --language go --non-interactive --suppress-agent-init, with the Go feature flag set through the environment, exited 0 and wrote apphost.go, go.mod, aspire.config.json and .aspire/modules, which is what aspire-init.mdx describes. The flag was set because the CLI still requires it until Remove the Go AppHost experimental feature flag aspire#21183 removes it.
Starter scaffold: aspire new aspire-go-starter, run with a CLI built at the head of Make new Go AppHosts gofmt-clean, ignore the generated SDK and check every resource aspire#21193 and the same feature flag, exited 0 and wrote 8 files. The apphost.go fence is byte-identical to the written file after line-ending normalization, the go.mod fence matches its go.mod, and the file tree and aspire.config.json fence show what it wrote, with example port numbers and without two hidden bookkeeping files in .aspire/modules/. go build ./... and go vet ./... passed in the scaffolded project.
Negative control: a Go fence that calls a method that doesn't exist fails to compile, so the fence check can fail.
gofmt: flags only the existing main.go fence in go-host.mdx (4-space indentation), which this PR doesn't change.

Not run: pnpm build, an AppHost end to end, and aspire add or aspire restore against a Go AppHost. What the aspire new --language go, aspire add and aspire restore references say about Go comes from reading the CLI source. The Go fences compile against an SDK generated before the latest generator changes; they set no handle-typed option fields, so they should be unaffected, but only the starter's apphost.go fence was also built against a regenerated SDK, as part of the scaffolded project. The fence build also predates the two commits that remove the Go flag text and the commit that matches the starter's scaffold; none of them changes a Go fence.

Covers the starter template, project layout, aspire.config.json, aspire run, the generated SDK and aspire restore. Registers the page in the AppHost sidebar next to TypeScript. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Shows aspire add, the packages entry and complete PostgreSQL and Go, Python and Vite AppHosts, and clarifies that handles record their own errors. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Describes names and handles, optional parameters, the error model with Err() and FormatError, and cancellation tokens. Every Go snippet on the page compiles and vets against a generated SDK. The Go sidebar entry becomes a group with Get started and API conventions, and the getting started page links to the new page. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Adds a Go row to the AppHost languages table and lists Go next to C# and TypeScript as an AppHost language. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Adds the Go guest process, the ATS to Go type mapping, and a Go column to the same-model syntax table. Type mappings were read from a generated Go SDK. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Add a Go tab next to each C# and TypeScript AppHost example in the Go hosting integration reference. Replace the experimental templates section with a pointer to the Go AppHost pages and update the Go getting started page to match. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

The restore and add pages describe the generated SDK for TypeScript and Go AppHosts and show a Go example. The new page lists the Go templates and documents --language. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

aspire init --language go creates apphost.go, go.mod, aspire.config.json and the generated .aspire/modules/ SDK (ran it with the dev CLI in an empty folder, exit 0). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Copilot

🟡 Changes recommended

The feature-flag instructions do not enable Go support, and complete examples discard resource errors.

4 open issues

What changed in this PR

Adds Go AppHost documentation alongside C# and TypeScript guidance for the Aspire 17.0 release.

Changes:

Adds getting-started and API-conventions guides with sidebar navigation.
Adds Go examples and updates language and architecture guidance.
Documents Go support in CLI creation, initialization, integration, and restore commands.

File	Description
src/frontend/src/content/docs/reference/cli/commands/aspire-restore.mdx	Documents Go SDK restoration.
src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx	Lists Go templates and language selection.
src/frontend/src/content/docs/reference/cli/commands/aspire-init.mdx	Documents Go AppHost initialization.
src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx	Explains adding integrations to Go AppHosts.
src/frontend/src/content/docs/languages-and-runtimes/index.mdx	Lists Go as an AppHost language.
src/frontend/src/content/docs/integrations/frameworks/go/go-host.mdx	Adds Go AppHost examples.
src/frontend/src/content/docs/integrations/frameworks/go/go-get-started.mdx	Links to the new Go guide.
src/frontend/src/content/docs/architecture/multi-language-architecture.mdx	Explains Go’s shared architecture.
src/frontend/src/content/docs/app-host/go-apphost.mdx	Adds setup and orchestration guidance.
src/frontend/src/content/docs/app-host/go-apphost-conventions.mdx	Explains Go API conventions.
src/frontend/config/sidebar/docs.topics.ts	Adds navigation for both new guides.

_{Review effort: Balanced}

aspire-repo-bot · 2026-10-20T06:21:42Z

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1924. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

Scalar fields (string, number, bool, enum) of a generated <Method>Options struct are pointers. Slices, maps, callbacks, and any are already nilable, so they are not pointers. Say that same-named methods share one struct or qualify its name with the handle type, and that a few methods take an existing type such as DelveServerOptions with its own field types. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

The first example discarded the handle that AddGoApp returns and checked only builder.Err(), which never sees a failed Add call because the error is recorded on the returned handle. Keep the api handle, check each resource before Build, and update the explanation to match the Errors section of the conventions page. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

The Go tab discarded the handle that AddGoApp returns and never checked it before Build, so a failed call went unseen. Keep the api handle and check its error, as the conventions page shows for a single resource. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

The Go AppHost no longer needs a feature flag, so the page no longer asks readers to enable one before creating or running a Go AppHost. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Go is no longer a feature flag, so drop its row from the settings table and use Rust, which still has a flag, as the example for global polyglot flags. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Show what aspire new aspire-go-starter writes: the .gitignore that lists .aspire/, .vscode/extensions.json, and the http launch profile. Reword the .gitignore tip, because the starter now adds that entry itself. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

> [!NOTE] > **Works with** microsoft/aspire#21173, the CLI support for `aspire docs api --language go`. Neither PR blocks the other: that PR is safe to land first, because the Go scope stays empty until these pages are published. > > **Needed by** #1923 and #1924, whose links to `/reference/api/go/` resolve only once this PR is on `release/17.0`. ## Summary  Adds a Go API reference at `/reference/api/go/**`, shaped like the TypeScript reference: index, module, item and member pages as HTML and `.md`, with sidebar, search and sitemap entries. This is the first step of Go AppHost GA (microsoft/aspire#21115). The reference goes first because its route and markdown shape is what `aspire docs api` parses from the sitemap. What changes: - **Generator.** `AtsJsonGenerator` gains a Go mode (`--language go`). It ports the Go SDK generator's naming and type rules (PascalCase, `(T, error)` results, trailing `opts ...*XxxOptions`, pointers, `*List[T]`, `*Dict[K,V]`) and reads the same `aspire sdk dump` JSON as the TypeScript mode. - **Pipeline.** `generate-ts-api-json.ps1` takes `-Language typescript|go`. `pnpm update:go-api`, `update-integration-data.ps1` and the normalizer handle Go data. `update-integration-data.yml` stages `src/frontend/src/data/go-modules` and its timeout goes from 45 to 75 minutes, since the job now runs C#, TypeScript and Go passes. - **Data.** 122 modules in `src/frontend/src/data/go-modules/` (5.75 MB), generated from the same package versions as `ts-modules`. - **Site.** `go-*` utilities, a `GoMemberCard` component and `reference/api/go/**` routes, plus registrations in the reference sidebar, search, overview and dev hub. The dev hub gets a `Go API` reference link, so the item count assertion in `dev-layout.spec.ts` goes from 30 to 31. - **Doc text.** Doc comments render through a `GoDocText` component. Backtick spans are styled inline code. An `{@ats-ref}` marker links to the type page, or to the package function page for an extension method, when the target is in the same module, and stays styled code otherwise. The markdown routes keep the code spans and render markers as plain code, without links. CLR generic arity markers are stripped from method names in both. - **Sidebar casing.** The Reference, Deployment and Community topic groups and the Reference overview title use sentence case ("Aspire reference", "Aspire deployment", "Aspire community"), like "Aspire integrations" and "Aspire dashboard". - **Tests.** Generator tests for Go mode, vitest suites for routes, markdown, doc text, search, sidebar and the whole seed (`pnpm test:unit:go-api`), and Playwright specs for Go search and sidebar. Existing cross-language specs also cover Go. The version-dropdown scenario for Go is its own test in `filter-navigation.spec.ts`: the existing test already uses 48 to 75 s of its 120 s budget on `release/17.0` CI, so a fourth iteration would leave little margin. Design notes: - A module is the contributing NuGet package (for example `Aspire.Hosting.Redis`), as in TypeScript. The Go SDK itself is one flat package, so each module page states the import path. - The pages carry no experimental or feature-flag notice. The Go AppHost doesn't require a flag at GA (microsoft/aspire#21106). - The Go code copies the TypeScript route and markdown logic into new files and keeps edits to shared files additive, which limits conflicts with the main to release sync. Consolidating the two is a follow-up on `main`. - The 24 `Aspire.Hosting.Azure.Provisioning.<Service>` proxy packages are left out. They would add 72 MB (1.28x the TypeScript data) and their pins are stale on `release/17.0`. The base `Aspire.Hosting.Azure.Provisioning` package is included. Not in this PR: - `<ApiReference>` Go links and a Go option in the AppHost language switcher. The switcher is hard-wired to `csharp|typescript` and needs Go docs tabs first (microsoft/aspire#21112). - `go-modules` in `merge-main-into-release.sh` `generated_dirs` and its test. Add it after the post-GA swap, when `main` has Go data. - Doc fidelity gaps, listed in the generator README: callback properties on core DTOs render as `func(...any) any`, and foreign enums and hand-written SDK types have no pages. A Go `IApiReferenceExporter` (`aspire sdk export --language go`) would replace the dump-derived signatures. Notes: - The data is 13.x-based until the 17.0 packages publish. The updater's PR uses `--base main`, so refreshing 17.0 data needs a manual run and a `release/17.0` base. - Scheduled runs of the updater on `main` fail at `generate-package-json.ps1:112` (`$_.apiReference` under StrictMode). That is unrelated and untouched here. ## Third-party links and affiliations  None. No third-party links are hand-written in this PR. The generated Go data carries the same upstream package and doc-comment URLs as the existing `ts-modules` data: 13 distinct hosts, every one already present there. ## Validation  The frontend commands run in `src/frontend` with `CI=1`. The unit, lint and markdown crawl results below are for the final head. The local `pnpm build` and Playwright results are from `d7d7633e41`, before the doc text and sidebar casing commits. CI on the final head `e506f71a33` passed all 17 checks, including the frontend build and the six Playwright shards (desktop, tablet and mobile Chromium, two shards each). - `dotnet test tests/AtsJsonGenerator.Tests/AtsJsonGenerator.Tests.csproj --nologo -v q`: 113 passed. - `pnpm test:unit:go-api`: 211 passed (14 files). - `pnpm test:unit`: 1374 passed, 1 skipped (94 files). - `pnpm lint`: no warnings. - Every Go `.md` route crawled on a local dev server that includes this branch: 3,130 pages (1 index, 122 module, 1,902 item, 1,105 member). All return 200 `text/markdown` with no `{@` markers left and no unbalanced backticks, and the crawled set equals what `getStaticPaths` generates. - `pnpm build`: exit 0 in 16 min 51 s on a 28-core machine, 35,616 pages, internal links valid. The sitemap has 3,130 Go, 19,293 TypeScript and 4,914 C# API URLs. - `pnpm exec playwright test --project=desktop-chromium --retries=0` on the Go specs and the specs extended for Go: 125 passed, 1 skipped. - Full Playwright suite on desktop, tablet and mobile (535, 535 and 531 tests, the three projects running at once on one machine): 524, 488 and 484 passed. 12 tests failed across the three runs. The `dev-layout.spec.ts` hub item count failed in all three and was a real regression from the new `Go API` link; it is fixed in this PR. The other 9 failures were timeouts under that load (`dev-browse`, `filter-navigation`, `gallery-search-contract` and one mobile `dev-layout` test). Every failing test passed when rerun alone with `--workers=1 --retries=0`, and `filter-navigation.spec.ts` passes in full on all three projects after the version-dropdown split. - Full regeneration of all 122 modules through `generate-ts-api-json.ps1 -Language go` and the normalizer matched the checked-in data with 0 diffs. After the Foundry fix below, `Aspire.Hosting` and `Aspire.Hosting.Foundry` were regenerated again: core is byte-identical and Foundry matches the committed file. - `aspire docs api list|search|get` against a local build of this site, using the CLI from microsoft/aspire#21173: `list go` returns 122 modules, `search "redis password" --language go` ranks `go/aspire.hosting.redis/redisresource/withpassword` first, and C# and TypeScript output is identical to the previous CLI. - A review pass found one issue: composite exported values in `Aspire.Hosting.Foundry` (201 `FoundryModels.*` entries) rendered as multi-line JSON, which split markdown bullets across lines. Fixed in the generator with a regression test, and a whole-seed vitest now guards every module. --------- Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

David Pine (IEvangelist) and others added 8 commits October 20, 2026 00:13

Add Go to the AppHost languages overview

c53ee3e

Adds a Go row to the AppHost languages table and lists Go next to C# and TypeScript as an AppHost language. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Copilot AI balanced review requested due to automatic review settings October 20, 2026 05:59

David Pine (IEvangelist) requested review from David Fowler (davidfowl), Eric Erhardt (eerhardt), Maddy Montaquila (maddymontaquila) and Mitch Denny (mitchdenny) as code owners October 20, 2026 05:59

Copilot started reviewing on behalf of David Pine (IEvangelist) October 20, 2026 05:59

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

David Pine (IEvangelist) and others added 3 commits October 20, 2026 03:30

This was referenced Oct 20, 2026

CLI configuration reference: use the flat experimentalPolyglot keys #1925

Open

AppHost-language selector: teach the docs site about Go #1926

Open

David Pine (IEvangelist) marked this pull request as draft October 20, 2026 13:29

David Pine (IEvangelist) and others added 2 commits October 20, 2026 09:08

David Pine (IEvangelist) mentioned this pull request Oct 21, 2026

Make new Go AppHosts gofmt-clean, ignore the generated SDK and check every resource microsoft/aspire#21193

Open

4 of 14 tasks

David Pine (IEvangelist) mentioned this pull request Oct 20, 2026

Add Go API reference #1917

Merged

David Pine (IEvangelist) marked this pull request as ready for review October 21, 2026 21:45

David Pine (IEvangelist) merged commit b40962d into release/17.0 Oct 22, 2026
27 of 30 checks passed

David Pine (IEvangelist) deleted the ievangelist-go-docs-snippets branch October 22, 2026 14:35

Navigation Menu

Repository navigation

Document the Go AppHost: getting started, conventions and CLI references - #1924

Document the Go AppHost: getting started, conventions and CLI references#1924
David Pine (IEvangelist) merged 14 commits into
release/17.0from
ievangelist-go-docs-snippets

David Pine (IEvangelist) commented Oct 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aspire-repo-bot Bot commented Oct 20, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

David Pine (IEvangelist) commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Third-party links and affiliations

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aspire-repo-bot Bot commented Oct 20, 2026

Frontend HTML artifact ready

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

David Pine (IEvangelist) commented Oct 20, 2026 •

edited

Loading