GoHostingExtensions Methods

ClassMethods10 members

Provides extension methods for adding Go applications to an Hosting.IDistributedApplicationBuilder.

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)
    {
        // ...
    }
}

GoHostingExtensions.cs#L82-L327

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[])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)
    {
        // ...
    }
}

GoHostingExtensions.cs#L343-L345

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>)extensionIResourceBuilder<T>

Starts a headless Delve debug server so that a DAP-compatible client can attach remotely. The application is launched with dlv 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)
    {
        // ...
    }
}

GoHostingExtensions.cs#L640

Parameters

builderIResourceBuilder<T>The resource builder for the Go application.

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 to launch.json with "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();

WithDelveServer(IResourceBuilder<T>, int)extensionIResourceBuilder<T>

Starts a headless Delve debug server on the specified port.

public static class GoHostingExtensions
{
    public static IResourceBuilder<T> WithDelveServer<T>(
        this IResourceBuilder<T> builder,
        int port = 2345)
    {
        // ...
    }
}

GoHostingExtensions.cs#L664

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

This overload is retained for binary compatibility. Use GoHostingExtensions.WithDelveServer for the default port or GoHostingExtensions.WithDelveServer to configure the port and other Delve server options.

Examples

builder.AddGoApp("api", "../go-api")
       .WithDelveServer(new DelveServerOptions { Port = 3456 });

WithDelveServer(IResourceBuilder<T>, DelveServerOptions?)extensionIResourceBuilder<T>

Starts a configurable headless Delve debug server so that DAP-compatible clients can attach remotely. The application is launched with dlv 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,
        DelveServerOptions? options = null)
    {
        // ...
    }
}

GoHostingExtensions.cs#L699-L726

Parameters

builderIResourceBuilder<T>The resource builder for the Go application.

optionsDelveServerOptions?optionalThe options that configure the Delve server. When null, the default options are used.

Returns

IResourceBuilder<T>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Remarks

The server listens on 127.0.0.1 and accepts a single debugger client by default. Set DelveServerOptions.AcceptMultiClient to true only when multiple clients or reconnections are required.

Examples

builder.AddGoApp("api", "../go-api")
       .WithDelveServer(new DelveServerOptions
       {
           Port = 2345,
           ContinueOnStart = true,
           Log = true,
           LogOutput = "rpc,dap,debugger"
       });

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")
    {
        // ...
    }
}

GoHostingExtensions.cs#L582-L596

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>)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)
    {
        // ...
    }
}

GoHostingExtensions.cs#L457-L490

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>)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)
    {
        // ...
    }
}

GoHostingExtensions.cs#L360-L395

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>)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)
    {
        // ...
    }
}

GoHostingExtensions.cs#L411-L441

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>)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)
    {
        // ...
    }
}

GoHostingExtensions.cs#L505-L527

Parameters

builderIResourceBuilder<T>The resource builder for the Go application.

Returns

IResourceBuilder<T>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.