GoHostingExtensions Methods
ClassMethods8 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)extensionIResourceBuilder<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
builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder to add the resource to.namestringThe name of the resource.appDirectorystring 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. packagePathstringoptional 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. buildTagsstring[]?optionalOptional build tags passed to the compiler via -tags (e.g. "netgo", "integration").ldFlagsstring?optionalOptional linker flags passed via -ldflags (e.g. "-X main.version=1.0.0").gcFlagsstring?optionalOptional compiler flags passed via -gcflags (e.g. "all=-N -l" to disable optimisations for Delve).raceDetectorbooloptionalWhen 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[])extensionIResourceBuilder<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
builderIResourceBuilder<T>The resource builder for the Go application.argsobject[]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)extensionIResourceBuilder<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
builderIResourceBuilder<T>The resource builder for the Go application.portintoptionalThe 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)extensionIResourceBuilder<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
builderIResourceBuilder<T>The resource builder for the Go application.privatePatternsstring[] 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. authHoststringThe Git host that requires authentication, e.g. "github.com".usernameArgNamestringoptional The Docker build-arg name for the Git username. Defaults to "GIT_USER". Pass it at build time with --build-arg GIT_USER=myuser. tokenSecretIdstringoptional 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>)extensionIResourceBuilder<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
builderIResourceBuilder<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>)extensionIResourceBuilder<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
builderIResourceBuilder<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>)extensionIResourceBuilder<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
builderIResourceBuilder<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>)extensionIResourceBuilder<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
builderIResourceBuilder<T>The resource builder for the Go application.Returns
IResourceBuilder<T>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.