Skip to main content
Aspire provides a rich set of extension methods on IDistributedApplicationBuilder for adding resources to your application. These methods follow a consistent pattern and return IResourceBuilder<T> for fluent configuration.

​
Pattern Overview

All resource extension methods follow this pattern: 
public static IResourceBuilder<TResource> Add{ResourceType}(
    this IDistributedApplicationBuilder builder,
    string name,
    // Resource-specific parameters
)
  • Returns IResourceBuilder<TResource> for method chaining
  • name parameter must be unique within the application
  • Names are case-insensitive

​
Container Resources

​
AddContainer

Adds a generic Docker container. 
builder.AddContainer("redis", "redis");
​
name
string
required
Unique name for the container resource.
​
image
string
required
Container image name (without tag).
​
tag
string
default:"latest"
Container image tag.

​
AddDockerfile

Builds a container from a Dockerfile. 
builder.AddDockerfile("myapp", "./src/MyApp");
​
name
string
required
Unique name for the container resource.
​
contextPath
string
required
Build context path (relative to app host or absolute).
​
dockerfilePath
string
default:"Dockerfile"
Path to Dockerfile relative to context path.
​
stage
string
Target stage in multi-stage Dockerfile.

​
.NET Project Resources

​
AddProject

Adds a .NET project to the application. 
builder.AddProject<Projects.Api>("api");
​
TProject
Type
required
Type from the project’s generated metadata (e.g., Projects.Api).
​
name
string
required
Unique name for the project resource.
​
launchProfileName
string
Name of the launch profile to use from launchSettings.json.
The Projects class is generated by the Aspire SDK based on project references in your app host.

​
Executable Resources

​
AddExecutable

Runs an arbitrary executable program. 
builder.AddExecutable("tool", "dotnet", "/path/to/project")
       .WithArgs("run");
​
name
string
required
Unique name for the executable resource.
​
command
string
required
Command or path to executable.
​
workingDirectory
string
required
Working directory for the executable.

​
AddNpmApp

Runs a Node.js application using npm. 
builder.AddNpmApp("frontend", "../ClientApp")
       .WithNpmCommand("start")
       .WithHttpEndpoint(port: 3000);
​
name
string
required
Unique name for the npm app resource.
​
workingDirectory
string
required
Directory containing package.json.
​
scriptName
string
default:"start"
npm script to run from package.json.

​
Database Resources

​
SQL Server

var sql = builder.AddSqlServer("sql");
var db = sql.AddDatabase("mydb");

builder.AddProject<Projects.Api>("api")
       .WithReference(db);
​
AddSqlServer(name, port)
IResourceBuilder<SqlServerServerResource>
Adds a SQL Server container.Parameters:
  • name - Resource name
  • port - Optional external port
​
AddDatabase(name)
IResourceBuilder<SqlServerDatabaseResource>
Adds a database to the SQL Server instance.Parameters:
  • name - Database name (also used as resource name)

​
PostgreSQL

var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("mydb");

builder.AddProject<Projects.Api>("api")
       .WithReference(db);
​
AddPostgres(name, port, password)
IResourceBuilder<PostgresServerResource>
Adds a PostgreSQL container.Parameters:
  • name - Resource name
  • port - Optional external port
  • password - Optional password parameter
​
AddDatabase(name)
IResourceBuilder<PostgresDatabaseResource>
Adds a database to the PostgreSQL instance.

​
Redis

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.Api>("api")
       .WithReference(cache);
​
AddRedis(name, port)
IResourceBuilder<RedisResource>
Adds a Redis container.Parameters:
  • name - Resource name
  • port - Optional external port

​
MongoDB

var mongo = builder.AddMongoDB("mongodb");
var db = mongo.AddDatabase("mydb");

builder.AddProject<Projects.Api>("api")
       .WithReference(db);
​
AddMongoDB(name, port)
IResourceBuilder<MongoDBServerResource>
Adds a MongoDB container.
​
AddDatabase(name)
IResourceBuilder<MongoDBDatabaseResource>
Adds a database to the MongoDB instance.

​
Message Queue Resources

​
RabbitMQ

var messaging = builder.AddRabbitMQ("messaging");

builder.AddProject<Projects.Worker>("worker")
       .WithReference(messaging);
​
AddRabbitMQ(name, port)
IResourceBuilder<RabbitMQServerResource>
Adds a RabbitMQ container with AMQP endpoint.Parameters:
  • name - Resource name
  • port - Optional external port for AMQP

​
Kafka

var kafka = builder.AddKafka("kafka");

builder.AddProject<Projects.Consumer>("consumer")
       .WithReference(kafka);
​
AddKafka(name, port)
IResourceBuilder<KafkaServerResource>
Adds a Kafka container with KRaft mode (no ZooKeeper).

​
Parameter Resources

​
AddParameter

Adds a configurable parameter that can be set at runtime. 
var apiKey = builder.AddParameter("api-key");

builder.AddProject<Projects.Api>("api")
       .WithEnvironment("API_KEY", apiKey);
​
name
string
required
Parameter name.
​
secret
bool
default:false
Whether the parameter contains sensitive data (masked in UI).
​
default
string
Optional default value.
Parameters can be set via:
  • Configuration (appsettings.json)
  • Environment variables
  • Command-line arguments
  • User secrets (for secret parameters)

​
Azure Resources

See the Azure hosting integrations documentation for:
  • AddAzureCosmosDB
  • AddAzureStorage
  • AddAzureServiceBus
  • AddAzureKeyVault
  • And more…

​
External Services

​
AddExternalService

References an external service not managed by Aspire. 
var externalApi = builder.AddExternalService("external-api", 
    new Uri("https://api.example.com/"));

builder.AddProject<Projects.Api>("api")
       .WithReference(externalApi);
​
name
string
required
Resource name for the external service.
​
uri
Uri
required
Absolute URI of the external service (or parameter containing the URI).

​
Resource Naming

Resource names must be unique within the application and are case-insensitive. Duplicate names throw DistributedApplicationException.
Name Validation
// This throws an exception:
builder.AddRedis("cache");
builder.AddPostgres("Cache");  // Case-insensitive conflict!

// Use unique names:
builder.AddRedis("redis-cache");
builder.AddPostgres("postgres-db");

​
Method Chaining

All Add methods return IResourceBuilder<T> for fluent configuration:
Complete Configuration
builder.AddPostgres("postgres")
       .WithDataVolume("postgres-data")
       .WithEnvironment("POSTGRES_DB", "mydb")
       .WithLifetime(ContainerLifetime.Persistent)
       .AddDatabase("appdb");

Build docs developers (and LLMs) love

Get started for freeTalk to us