Skip to main content
The IResourceBuilder<T> interface provides a fluent API for configuring resources in .NET Aspire applications. Every resource added to an application returns a builder that enables method chaining for configuration.

​
Interface Definition

public interface IResourceBuilder<out T> where T : IResource
{
    IDistributedApplicationBuilder ApplicationBuilder { get; }
    T Resource { get; }
    IResourceBuilder<T> WithAnnotation<TAnnotation>(TAnnotation annotation, 
        ResourceAnnotationMutationBehavior behavior = ResourceAnnotationMutationBehavior.Append) 
        where TAnnotation : IResourceAnnotation;
}

​
Properties

​
ApplicationBuilder
IDistributedApplicationBuilder
Gets the distributed application builder that owns this resource builder. Use this to access application-level configuration or add related resources.
​
Resource
T
Gets the resource being built. Access this to read or modify resource properties directly.

​
Core Methods

​
WithAnnotation

Adds metadata and configuration to resources through annotations.
​
WithAnnotation<TAnnotation>(annotation, behavior)
IResourceBuilder<T>
Adds an annotation to the resource being built.Parameters:
  • annotation - The annotation instance to add
  • behavior - Controls how the annotation is added:
    • Append (default) - Add the annotation to existing annotations
    • Replace - Replace any existing annotation of the same type
Returns: The resource builder for method chaining
Using Annotations
var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithAnnotation(new CustomAnnotation { Value = "example" })
       .WithAnnotation(new AnotherAnnotation(), ResourceAnnotationMutationBehavior.Replace);

​
Common Configuration Methods

These extension methods are available on IResourceBuilder<T> for different resource types:

​
Environment Variables

Available for resources implementing IResourceWithEnvironment. 
builder.AddContainer("api", "myapi")
       .WithEnvironment("ASPNETCORE_ENVIRONMENT", "Production")
       .WithEnvironment("LOG_LEVEL", "Information");
​
WithEnvironment(name, value)
IResourceBuilder<T>
Adds a static environment variable.Parameters:
  • name - Variable name
  • value - Variable value (string, parameter, endpoint reference, or expression)
​
WithEnvironment(callback)
IResourceBuilder<T>
Adds environment variables through a callback for computed or dynamic values.Parameters:
  • callback - Action or async function receiving EnvironmentCallbackContext

​
Command-Line Arguments

Available for resources implementing IResourceWithArgs. 
builder.AddExecutable("tool", "dotnet", workingDirectory: "/app")
       .WithArgs("run", "--configuration", "Release");
​
WithArgs(params string[])
IResourceBuilder<T>
Adds static command-line arguments.Parameters:
  • args - Array of argument strings
​
WithArgs(callback)
IResourceBuilder<T>
Adds arguments through a callback for computed values.Parameters:
  • callback - Action or async function receiving CommandLineArgsCallbackContext

​
Endpoints

Available for resources implementing IResourceWithEndpoints. 
builder.AddProject<Projects.Api>("api")
       .WithHttpEndpoint(port: 8080, name: "http");
​
WithHttpEndpoint(port, name)
IResourceBuilder<T>
Adds an HTTP endpoint.Parameters:
  • port - Optional external port number
  • name - Optional endpoint name (defaults to “http”)
​
WithHttpsEndpoint(port, name)
IResourceBuilder<T>
Adds an HTTPS endpoint.Parameters:
  • port - Optional external port number
  • name - Optional endpoint name (defaults to “https”)
​
WithEndpoint(targetPort, port, scheme, name)
IResourceBuilder<T>
Adds a custom endpoint with full control over configuration.Parameters:
  • targetPort - Port the resource listens on
  • port - Optional external port
  • scheme - URI scheme (http, https, tcp, etc.)
  • name - Optional endpoint name
​
WithEndpoint(name, callback, createIfNotExists)
IResourceBuilder<T>
Modifies an existing endpoint or creates a new one.Parameters:
  • name - Endpoint name
  • callback - Action to modify the EndpointAnnotation
  • createIfNotExists - Create the endpoint if it doesn’t exist

​
Getting Endpoint References

​
GetEndpoint(name)
EndpointReference
Gets a reference to an endpoint that can be used in references or environment variables.Parameters:
  • name - Endpoint name
Returns: An EndpointReference that resolves to the endpoint URL at runtime
Endpoint References
var api = builder.AddProject<Projects.Api>("api")
                 .WithHttpsEndpoint();

var frontend = builder.AddNpmApp("frontend", "../frontend")
                      .WithEnvironment("API_URL", api.GetEndpoint("https"));

​
Resource References

Create dependencies between resources using WithReference. 
var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("mydb");

builder.AddProject<Projects.Api>("api")
       .WithReference(db);  // Injects ConnectionStrings__mydb
​
WithReference(source)
IResourceBuilder<TDestination>
Adds a reference to another resource, injecting connection strings and/or service discovery information.Parameters:
  • source - The resource builder to reference
  • connectionName - Optional custom name for connection string (only for IResourceWithConnectionString)
  • optional - Whether the connection string is optional

​
Container-Specific Methods

For resources that are ContainerResource:

​
Image Configuration

builder.AddContainer("redis", "redis");

​
Volumes and Bind Mounts

builder.AddContainer("postgres", "postgres")
       .WithVolume("postgres-data", "/var/lib/postgresql/data");
​
WithVolume(name, target, isReadOnly)
IResourceBuilder<T>
Adds a Docker volume to the container.Parameters:
  • name - Optional volume name (null creates anonymous volume)
  • target - Mount path in container
  • isReadOnly - Whether the volume is read-only
​
WithBindMount(source, target, isReadOnly)
IResourceBuilder<T>
Mounts a host directory or file into the container.Parameters:
  • source - Host path (relative to app host directory unless absolute)
  • target - Mount path in container
  • isReadOnly - Whether the mount is read-only

​
Container Runtime

builder.AddContainer("myapp", "myapp")
       .WithEntrypoint("/app/startup.sh");

​
Publishing Configuration

​
WithManifestPublishingCallback(callback)
IResourceBuilder<T>
Customizes how the resource is written to the deployment manifest.Parameters:
  • callback - Action or async function receiving ManifestPublishingContext
Custom Manifest Output
builder.AddContainer("myapp", "myapp")
       .WithManifestPublishingCallback(context => 
       {
           context.Writer.WriteString("customProperty", "value");
       });

​
Method Chaining Pattern

All builder methods return IResourceBuilder<T>, enabling fluent configuration:
Complete Example
var builder = DistributedApplication.CreateBuilder(args);

var apiKey = builder.AddParameter("api-key", secret: true);
var cache = builder.AddRedis("cache");

builder.AddProject<Projects.Api>("api")
       .WithHttpsEndpoint(port: 8443)
       .WithEnvironment("API_KEY", apiKey)
       .WithEnvironment("ASPNETCORE_ENVIRONMENT", "Production")
       .WithReference(cache)
       .WithReplicas(3);

Build docs developers (and LLMs) love

Get started for freeTalk to us