Skip to main content
.NET Aspire applications are composed of resources - the building blocks of your distributed application. Resources represent the services, databases, message queues, and other components that make up your system.

​
What is a Resource?

A resource is any component in your application that implements the IResource interface. Every resource has:
  • A name - Used for service discovery and identification
  • Annotations - Metadata that describes configuration, endpoints, and behavior
  • A type - Determines how the resource is deployed and managed

​
Resource Types

.NET Aspire supports three primary compute resource types:

Projects

.NET applications running in your solution

Containers

Docker containers for databases, caches, etc.

Executables

Any command-line program or process

​
Project Resources

Project resources represent .NET projects in your solution. They’re automatically compiled, run, and monitored.

​
Adding a Project

Reference a project that’s already in your solution:
var api = builder.AddProject<Projects.Api>("api");
The Projects.Api type is auto-generated when you add a project reference to your AppHost project.

​
Project Configuration

1
Launch profiles
2
Aspire automatically reads launchSettings.json to configure endpoints. You can specify which profile to use:
3
var api = builder.AddProject<Projects.Api>("api", launchProfileName: "Production");
4
Or exclude launch profiles entirely:
5
var api = builder.AddProject<Projects.Api>("api", options =>
{
    options.ExcludeLaunchProfile = true;
});
6
Endpoints from Kestrel
7
Project endpoints are automatically discovered from Kestrel configuration. If your project’s appsettings.json contains:
8
{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}
9
These endpoints are automatically added to the project resource.
10
Replicas
11
Scale a project to multiple instances:
12
var api = builder.AddProject<Projects.Api>("api")
                 .WithReplicas(3);

​
Container Resources

Container resources run Docker or Podman containers. They’re perfect for databases, caches, message queues, and third-party services.

​
Adding a Container

// Basic container
var nginx = builder.AddContainer("nginx", "nginx", "latest");

// Or specify just the image (assumes 'latest' tag)
var nginx = builder.AddContainer("nginx", "nginx");

​
Common Container Configuration

// Expose ports
var app = builder.AddContainer("myapp", "myimage")
                 .WithHttpEndpoint(port: 8080, targetPort: 80, name: "http");

​
Advanced Container Options

Override the container’s entrypoint:
var app = builder.AddContainer("myapp", "myimage")
                 .WithEntrypoint("/bin/sh");
Control when containers are stopped:
// Keep container running after AppHost stops
var db = builder.AddContainer("postgres", "postgres")
                .WithLifetime(ContainerLifetime.Persistent);
Options:
  • Persistent - Container keeps running after AppHost stops
  • Session - Container stops when AppHost stops (default)
Add custom DNS names for container-to-container communication:
var api = builder.AddContainer("api", "myapi")
                 .WithContainerNetworkAlias("api-service");

​
Integration Resources

.NET Aspire provides pre-built integrations for common containers: 
// Instead of manually configuring Redis:
var cache = builder.AddContainer("cache", "redis")
                   .WithVolume("cache-data", "/data")
                   .WithEnvironment(...);

// Use the integration:
var cache = builder.AddRedis("cache");
Available integrations include PostgreSQL, SQL Server, Redis, MongoDB, RabbitMQ, Kafka, and many more. See the Hosting Integrations documentation.

​
Executable Resources

Executable resources run any command-line program. They’re useful for:
  • Node.js, Python, or other non-.NET applications
  • Build tools and scripts
  • Custom services that don’t run in containers

​
Adding an Executable

var npm = builder.AddExecutable("frontend", "npm", "./frontend", "run", "dev");
Parameters:
  1. name - Resource identifier
  2. command - The executable to run (must be in PATH or use full path)
  3. workingDirectory - Where to run the command
  4. args - Command-line arguments
For security, Aspire only runs executables found in your PATH environment variable. To run an executable in the current directory, use ./command (Linux/macOS) or .\\command.exe (Windows).

​
Executable Configuration

// Add arguments
var app = builder.AddExecutable("frontend", "npm", "./frontend")
                 .WithArgs("run", "dev");

// Or use callback for dynamic arguments
var app = builder.AddExecutable("frontend", "npm", "./frontend")
                 .WithArgs(context =>
                 {
                     context.Args.Add("run");
                     context.Args.Add(context.ExecutionContext.IsPublishMode ? "build" : "dev");
                 });

​
Node.js, NPM, and Yarn

Aspire provides specialized methods for JavaScript applications: 
var app = builder.AddNodeApp("frontend", "./frontend/app.js")
                 .WithEnvironment("NODE_ENV", "development");

​
Resource Builder Pattern

All resource methods return an IResourceBuilder<T>, enabling a fluent configuration syntax: 
var api = builder.AddProject<Projects.Api>("api")
                 .WithReplicas(3)
                 .WithEnvironment("ASPNETCORE_ENVIRONMENT", "Production")
                 .WithReference(cache)
                 .WithReference(database);
The builder provides methods to:
  • Configure the resource
  • Add annotations
  • Wire dependencies
  • Access the underlying resource

​
Working with Resources

​
Get a Resource Reference

The builder returns a typed reference you can use later: 
var cache = builder.AddRedis("cache");
var db = builder.AddPostgres("postgres").AddDatabase("mydb");

// Use references when wiring dependencies
var api = builder.AddProject<Projects.Api>("api")
                 .WithReference(cache)
                 .WithReference(db);

​
Resource Names

Every resource must have a unique name (case-insensitive): 
// This will throw an exception:
var db1 = builder.AddPostgres("database");
var db2 = builder.AddPostgres("database"); // ERROR: Duplicate name
Resource names are used for:
  • Service discovery
  • Dashboard display
  • Logging and diagnostics
  • Generated connection string keys

​
Next Steps

Wire Dependencies

Connect resources using WithReference

Configuration

Learn about configuration management

Environment Variables

Pass configuration to resources

Hosting Integrations

Explore pre-built integrations

Build docs developers (and LLMs) love

Get started for freeTalk to us