GoHostingExtensions Methods
Class Methods 8 members
Provides extension methods for adding Go applications to an
Hosting.IDistributedApplicationBuilder. AddGoApp(IDistributedApplicationBuilder, string, string, string, string[]?, string?, string?, bool) Section titled AddGoApp(IDistributedApplicationBuilder, string, string, string, string[]?, string?, string?, bool) extension IResourceBuilder<GoAppResource> Adds a Go application to the application model. The Go toolchain must be available on the PATH.
public static class GoHostingExtensions{ public static IResourceBuilder<GoAppResource> AddGoApp( this IDistributedApplicationBuilder builder, string name, string appDirectory, string packagePath = ".", string[]? buildTags = null, string? ldFlags = null, string? gcFlags = null, bool raceDetector = false) { // ... }}Parameters
builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder to add the resource to. name string The name of the resource. appDirectory string The path to the directory that acts as both the Go module root (where go.mod lives) and the Docker build context for aspire publish. packagePath string optional The Go package to run or build, relative to appDirectory. Defaults to "." (the module root itself). Use a sub-path such as "./cmd/server" when the main package is not at the module root (e.g. api/cmd/server/main.go with api/go.mod). This value is passed to go run, dlv debug, and go build consistently. buildTags string[]? optional Optional build tags passed to the compiler via -tags (e.g. "netgo", "integration"). ldFlags string? optional Optional linker flags passed via -ldflags (e.g. "-X main.version=1.0.0"). gcFlags string? optional Optional compiler flags passed via -gcflags (e.g. "all=-N -l" to disable optimisations for Delve). raceDetector bool optional When true, enables the Go race detector by passing -race to go run. Returns
IResourceBuilder<GoAppResource> A reference to the ApplicationModel.IResourceBuilder`1. Remarks
This method executes the Go application using go run .. The Go toolchain resolves the entry point from the package in appDirectory.
Go applications automatically have VS Code debugging support enabled via Delve. Use GoHostingExtensions.WithModTidy, GoHostingExtensions.WithModVendor, or GoHostingExtensions.WithModDownload to manage module dependencies before startup, and GoHostingExtensions.WithVetTool to run static analysis. Use GoHostingExtensions.WithAppArgs to pass runtime program arguments, and GoHostingExtensions.WithDelveServer to enable remote debugging via a headless Delve server.
Examples
Add a Go API to the application model with build tags and linker flags:
var builder = DistributedApplication.CreateBuilder(args);
builder.AddGoApp("api", "../go-api", buildTags: ["netgo"], ldFlags: "-X main.version=1.0.0") .WithHttpEndpoint(port: 8080) .WithExternalHttpEndpoints();
builder.Build().Run();WithAppArgs(IResourceBuilder<T>, object[]) Section titled WithAppArgs(IResourceBuilder<T>, object[]) extension IResourceBuilder<T> Passes extra arguments to the Go program at runtime. In normal run mode they appear after
go run .; in Delve mode after the -- separator. public static class GoHostingExtensions{ public static IResourceBuilder<T> WithAppArgs<T>( this IResourceBuilder<T> builder, params object[] args) { // ... }}Parameters
builder IResourceBuilder<T> The resource builder for the Go application. args object[] The program arguments (e.g., "serve", "--config", "prod.yaml"). Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for chaining. WithDelveServer(IResourceBuilder<T>, int) Section titled WithDelveServer(IResourceBuilder<T>, int) extension IResourceBuilder<T> Starts a headless Delve debug server so that any DAP-compatible client can attach remotely. The application is launched as
dlv --headless=true --listen=127.0.0.1:<port> --api-version=2 debug . instead of go run .. Delve must be available on the PATH. public static class GoHostingExtensions{ public static IResourceBuilder<T> WithDelveServer<T>( this IResourceBuilder<T> builder, int port = 2345) { // ... }}Parameters
builder IResourceBuilder<T> The resource builder for the Go application. port int optional The TCP port Delve listens on. Defaults to 2345. Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for chaining. Remarks
Delve is the only Go debugger; both GoLand and VS Code use it under the hood, just in different modes:
- GoLand — Create a Go Remote run configuration pointing at
localhost:<port>and start it after the resource has started. - VS Code (attach mode) — Add a
"request": "attach"entry tolaunch.jsonwith"mode": "remote","host": "localhost", and"port": <port>, then start it after the resource has started.
VS Code users who do not need GoLand compatibility can rely on the automatic VS Code debugging support that GoHostingExtensions.AddGoApp enables by default — no change to the application command is required in that case.
Examples
builder.AddGoApp("api", "../go-api") .WithDelveServer(port: 2345);WithGoPrivate(IResourceBuilder<T>, string[], string, string, string) Section titled WithGoPrivate(IResourceBuilder<T>, string[], string, string, string) extension IResourceBuilder<T> Configures private Go module authentication for publish-time Dockerfile generation.
public static class GoHostingExtensions{ public static IResourceBuilder<T> WithGoPrivate<T>( this IResourceBuilder<T> builder, string[] privatePatterns, string authHost, string usernameArgName = "GIT_USER", string tokenSecretId = "gittoken") { // ... }}Parameters
builder IResourceBuilder<T> The resource builder for the Go application. privatePatterns string[] One or more module path patterns that should bypass the public proxy and checksum database, e.g. "*.mycompany.com" or "github.com/myorg". Passed verbatim to GOPRIVATE, which implicitly covers GONOSUMCHECK and GONOPROXY. authHost string The Git host that requires authentication, e.g. "github.com". usernameArgName string optional The Docker build-arg name for the Git username. Defaults to "GIT_USER". Pass it at build time with --build-arg GIT_USER=myuser. tokenSecretId string optional The BuildKit secret ID for the Git access token. Defaults to "gittoken". Pass it at build time with --secret id=gittoken,src=/path/to/token. Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for chaining. Remarks
Only affects the generated Dockerfile — has no effect in run mode, where the local Go toolchain picks up credentials from the developer's own ~/.netrc or git credential helper.
The generated build stage writes a temporary .netrc file from the username build-arg and the token secret, runs go mod download, then removes the file — all in a single layer so credentials never persist in the image.
Examples
Build with: docker build --build-arg GIT_USER=myuser --secret id=gittoken,src=~/.git-token .
builder.AddGoApp("api", "../go-api") .WithGoPrivate(["github.com/myorg"], "github.com");WithModDownload(IResourceBuilder<T>) Section titled WithModDownload(IResourceBuilder<T>) extension IResourceBuilder<T> Runs
go mod download before starting the application, pre-fetching all module dependencies into the local module cache without modifying go.sum. The main application waits for the download step to complete successfully before launching. public static class GoHostingExtensions{ public static IResourceBuilder<T> WithModDownload<T>( this IResourceBuilder<T> builder) { // ... }}Parameters
builder IResourceBuilder<T> The resource builder for the Go application. Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for chaining. WithModTidy(IResourceBuilder<T>) Section titled WithModTidy(IResourceBuilder<T>) extension IResourceBuilder<T> Runs
go mod tidy before starting the application, ensuring go.sum is up to date. The main application waits for the tidy step to complete successfully before launching. public static class GoHostingExtensions{ public static IResourceBuilder<T> WithModTidy<T>( this IResourceBuilder<T> builder) { // ... }}Parameters
builder IResourceBuilder<T> The resource builder for the Go application. Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for chaining. WithModVendor(IResourceBuilder<T>) Section titled WithModVendor(IResourceBuilder<T>) extension IResourceBuilder<T> Runs
go mod vendor before starting the application, caching all module dependencies in the local vendor/ directory. The main application waits for the vendor step to complete successfully before launching. public static class GoHostingExtensions{ public static IResourceBuilder<T> WithModVendor<T>( this IResourceBuilder<T> builder) { // ... }}Parameters
builder IResourceBuilder<T> The resource builder for the Go application. Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for chaining. WithVetTool(IResourceBuilder<T>) Section titled WithVetTool(IResourceBuilder<T>) extension IResourceBuilder<T> Runs
go vet ./... before starting the application to catch static analysis issues. The main application waits for the vet step to complete successfully before launching. public static class GoHostingExtensions{ public static IResourceBuilder<T> WithVetTool<T>( this IResourceBuilder<T> builder) { // ... }}Parameters
builder IResourceBuilder<T> The resource builder for the Go application. Returns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 for chaining.