Skip to main content
The ProjectResource class represents a .NET project that can be run as part of your distributed application. It provides automatic service discovery, connection string injection, and seamless integration with the .NET ecosystem.

​
Class Definition

public class ProjectResource : Resource,
    IResourceWithEnvironment,
    IResourceWithArgs,
    IResourceWithServiceDiscovery,
    IResourceWithWaitSupport,
    IResourceWithProbes
{
    public ProjectResource(string name);
}

​
Constructor

​
name
string
required
Unique name for the project resource. Used for service discovery and references.

​
Adding Projects

​
Basic Project

builder.AddProject<Projects.Api>("api");
​
AddProject<TProject>(name, launchProfileName)
IResourceBuilder<ProjectResource>
Adds a .NET project to the application.Type Parameters:
  • TProject - Type from the generated Projects class (e.g., Projects.Api)
Parameters:
  • name - Unique resource name
  • launchProfileName - Optional launch profile from launchSettings.json
The Projects class is auto-generated by the Aspire SDK based on <ProjectReference> elements in your app host’s .csproj file.

​
Service Discovery

Project resources automatically participate in service discovery. Other services can reference them to get automatically configured HTTP/HTTPS endpoints.

​
Referencing Projects

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

builder.AddProject<Projects.Api>("api")
       .WithReference(db);
// Injects: ConnectionStrings__mydb={connectionString}

​
Service Discovery Environment Variables

When you reference a project with .WithReference(), these environment variables are automatically injected:
Service Discovery Variables
# For HTTPS endpoint named "https":
services__api__https__0=https://localhost:7001

# For HTTP endpoint named "http":
services__api__http__0=http://localhost:5000

# Multiple endpoints of the same scheme:
services__api__https__0=https://localhost:7001
services__api__https__1=https://localhost:7002
These variables work with .NET’s Service Discovery to automatically configure HttpClient instances.

​
Configuration

​
Environment Variables

builder.AddProject<Projects.Api>("api")
       .WithEnvironment("ASPNETCORE_ENVIRONMENT", "Production")
       .WithEnvironment("ASPNETCORE_URLS", "http://+:8080");

​
Launch Profiles

Use launch profiles from launchSettings.json:
launchSettings.json
{
  "profiles": {
    "Development": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "https://localhost:7001;http://localhost:5000"
    },
    "Production": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      },
      "applicationUrl": "https://localhost:8443"
    }
  }
}
Using Launch Profiles
builder.AddProject<Projects.Api>("api", launchProfileName: "Production");

​
Command-Line Arguments

builder.AddProject<Projects.Api>("api")
       .WithArgs("--urls", "http://+:8080");

​
Endpoints

Project resources automatically expose HTTP and HTTPS endpoints from their Kestrel configuration.

​
Adding Endpoints

builder.AddProject<Projects.Api>("api")
       .WithHttpEndpoint(port: 8080);

​
Endpoint References

var api = builder.AddProject<Projects.Api>("api")
                 .WithHttpsEndpoint();

var httpsEndpoint = api.GetEndpoint("https");

builder.AddProject<Projects.Frontend>("frontend")
       .WithEnvironment("API_URL", httpsEndpoint);

​
References and Dependencies

​
Database References

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

builder.AddProject<Projects.Api>("api")
       .WithReference(db);
// Injects: ConnectionStrings__mydb={connectionString}

​
Service References

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

builder.AddProject<Projects.Worker>("worker")
       .WithReference(rabbitmq);

​
Parameter References

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

builder.AddProject<Projects.Api>("api")
       .WithEnvironment("ExternalApi__ApiKey", apiKey);

​
Waiting for Dependencies

Ensure projects start in the correct order: 
var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("mydb");

builder.AddProject<Projects.Api>("api")
       .WithReference(db)
       .WaitFor(postgres);  // Wait for postgres to be ready

​
Replicas

Run multiple instances of a project: 
builder.AddProject<Projects.Api>("api")
       .WithReplicas(3);
// Starts 3 instances: api-0, api-1, api-2
​
WithReplicas(count)
IResourceBuilder<ProjectResource>
Creates multiple instances of the project.Parameters:
  • count - Number of replicas (must be > 0)
Each replica gets a unique name with an index suffix (e.g., api-0, api-1). Service discovery automatically includes all replica endpoints.

​
Publishing

When generating manifests for deployment, projects are published as container images.
Publishing Configuration
var api = builder.AddProject<Projects.Api>("api")
                 .WithHttpsEndpoint();

// During 'dotnet publish', this project will be:
// 1. Built as a container image
// 2. Included in the deployment manifest
// 3. Tagged with the registry from builder options

​
Complete Examples

​
Multi-Tier Application

Full Application
var builder = DistributedApplication.CreateBuilder(args);

// Database
var postgres = builder.AddPostgres("postgres")
                      .WithDataVolume();
var db = postgres.AddDatabase("appdb");

// Cache
var cache = builder.AddRedis("cache")
                   .WithDataVolume();

// Backend API
var apiKey = builder.AddParameter("api-key", secret: true);
var api = builder.AddProject<Projects.Api>("api")
                 .WithHttpsEndpoint(port: 7001)
                 .WithEnvironment("ExternalApi__ApiKey", apiKey)
                 .WithReference(db)
                 .WithReference(cache)
                 .WaitFor(postgres)
                 .WithReplicas(3);

// Worker Service
builder.AddProject<Projects.Worker>("worker")
       .WithReference(db)
       .WithReference(cache)
       .WaitFor(postgres);

// Frontend
builder.AddProject<Projects.Web>("frontend")
       .WithHttpsEndpoint(port: 7002)
       .WithReference(api)
       .WithExternalHttpEndpoints();

builder.Build().Run();

​
Microservices with Service Discovery

Service Discovery Example
var builder = DistributedApplication.CreateBuilder(args);

// Shared services
var postgres = builder.AddPostgres("postgres");
var cache = builder.AddRedis("cache");

// Order Service
var orderDb = postgres.AddDatabase("orders");
var orderService = builder.AddProject<Projects.OrderService>("order-service")
                          .WithReference(orderDb)
                          .WithReference(cache)
                          .WithHttpsEndpoint();

// Inventory Service  
var inventoryDb = postgres.AddDatabase("inventory");
var inventoryService = builder.AddProject<Projects.InventoryService>("inventory-service")
                              .WithReference(inventoryDb)
                              .WithHttpsEndpoint();

// API Gateway (references both services)
builder.AddProject<Projects.ApiGateway>("gateway")
       .WithReference(orderService)
       .WithReference(inventoryService)
       .WithHttpsEndpoint(port: 7000, isExternal: true);

builder.Build().Run();

Build docs developers (and LLMs) love

Get started for freeTalk to us