Adding Application Components via Add Methods

Using methods such as AddProject, AddContainer, AddExecutable, AddParameter, and AddConnectionString, you can orchestrate the app host into a complete application.

Configuring Explicit Resource Startup

builder.AddProject<Projects.MyApp>("dbmigration").WithExplicitStart();

Using the WithExplicitStart method, you can configure explicit resource startup; resources configured for explicit startup need to be started manually.

Referencing Resources with the WithReference Method

builder.AddProject<Projects.MyApp>("myapp").WithReference(postgresdb);

The referenced resource can be an endpoint, a connection string, or another resource. The referenced resource is passed to the referencing resource via environment variables.

Waiting for Resources to Start and Complete

builder.AddProject<Projects.MyApp>("myapp").WithWaitFor(postgresdb);

builder.AddProject<Projects.MyApp>("myapp").WithWaitForCompletion("dbmigration");

Customizing Container Startup Arguments

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

Container Resource Lifetime

var cache1 = builder.AddRedis("cache1").WithLifetime(ContainerLifetime.Persistent);
var cache2 = builder.AddRedis("cache1").WithLifetime(ContainerLifetime.Session);

Persistent means the container resource has a persistent lifetime, while Session means the container resource has a session lifetime.

External Parameters

Add the following node to the appsettings.json configuration file in the Host project.

{
    "Parameters": {
        "myvalue": "local-value"
    }
}

var value1 = builder.AddParameter("myvalue");
var value2 = builder.AddParameter("myvalue", secret: true);

builder.AddProject<Projects.ApiService>("api").WithEnvironment("EXAMPLE_VALUE", value1);

External Connection Strings

Add the following node to the appsettings.json configuration file in the Host project.

{
    "ConnectionStrings": {
        "myconnection": "Server=myserver;Database=mydb;User=myuser;Password=mypassword;"
    }
}

var connection = builder.AddConnectionString("myconnection");

builder.AddProject<Projects.ApiService>("api").WithReference(connection);

Endpoint References

var builder = DistributedApplication.CreateBuilder(args);

var customContainer = builder.AddContainer("myapp", "mycustomcontainer").WithHttpEndpoint(port: 9043, name: "endpoint");

var endpoint = customContainer.GetEndpoint("endpoint");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice").WithReference(endpoint);

Enabling Management Extensions on the Redis Component

var redis = builder.AddRedis("redis").WithRedisInsight();
var redis = builder.AddRedis("redis").WithRedisCommander();

Registering Lifecycle Hooks

using Aspire.Hosting.Lifecycle;
using Microsoft.Extensions.Logging;

var builder = DistributedApplication.CreateBuilder(args);

builder.Services.AddLifecycleHook<LifecycleLogger>();

builder.Build().Run();

class LifecycleLogger(ILogger<LifecycleLogger> logger): IDistributedApplicationLifecycleHook
{
    public Task BeforeStartAsync(DistributedApplicationModel appModel, CancellationToken cancellationToken = default)
    {
        logger.LogInformation("BeforeStartAsync");
        return Task.CompletedTask;
    }

    public Task AfterEndpointsAllocatedAsync(
        DistributedApplicationModel appModel, CancellationToken cancellationToken = default)
    {
        logger.LogInformation("AfterEndpointsAllocatedAsync");
        return Task.CompletedTask;
    }

    public Task AfterResourcesCreatedAsync(
        DistributedApplicationModel appModel, CancellationToken cancellationToken = default)
    {
        logger.LogInformation("AfterResourcesCreatedAsync");
        return Task.CompletedTask;
    }
}

Networking Model and Multiple Replicas

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066, IsExternal: true, IsProxied: true)
       .WithReplicas(2);

The IsExternal and IsProxied properties determine how an endpoint is managed and exposed. When IsExternal is true, the endpoint is exposed publicly; when IsProxied is true, the endpoint is proxied.

https://learn.microsoft.com/zh-cn/dotnet/aspire/fundamentals/networking-overview

Other Features

  • Custom resource commands
  • Adding Dockerfiles to the .NET app model
  • Capturing events in Aspire

References

https://learn.microsoft.com/zh-cn/dotnet/aspire