Dapr integration

⭐ Community Toolkit

Dapr (Distributed Application Runtime) is a portable, event-driven runtime that makes it easy for developers to build resilient, microservice stateless and stateful applications. The Aspire Dapr integration enables you to add Dapr sidecars to your Aspire projects.

Note

This integration requires the Dapr CLI to be installed on your machine. For installation instructions, see Install the Dapr CLI.

After installing the CLI, you must run dapr init to initialize Dapr on your local machine before using this integration.

Hosting integration

To get started with the Aspire Dapr hosting integration, install the CommunityToolkit.Aspire.Hosting.Dapr NuGet package in the app host project.

Install the NuGet package

dotnet add package CommunityToolkit.Aspire.Hosting.Dapr

Add Dapr sidecar

In your app host project, add a Dapr sidecar to a project using the WithDaprSidecar extension method:

var builder = DistributedApplication.CreateBuilder(args);
  
builder.AddProject<Projects.ExampleProject>("exampleproject")
       .WithDaprSidecar();
  
// After adding all resources, run the app...

By default, the Dapr sidecar uses the resource name as the Dapr app ID. You can customize the app ID and sidecar options:

var builder = DistributedApplication.CreateBuilder(args);
  
builder.AddProject<Projects.ExampleProject>("exampleproject")
       .WithDaprSidecar(new DaprSidecarOptions
       {
           AppId = "my-app-id",
           DaprGrpcPort = 50001,
           DaprHttpPort = 3500,
           MetricsPort = 9090
       });
  
// After adding all resources, run the app...

Dashboard integration

When you add Dapr sidecars to your projects, they appear as separate resources in the Aspire dashboard. Each sidecar is displayed with a unique name based on the project name and includes the configured ports.

Client integration

To connect to services with Dapr sidecars from your client application, use the Dapr.AspNetCore or Dapr.Client NuGet packages:

Install the NuGet package

dotnet add package Dapr.AspNetCore

For non-ASP.NET Core applications, use the Dapr.Client package instead:

dotnet add package Dapr.Client

Use Dapr client

In the Program.cs file of your client-consuming project, call the AddDaprClient extension method to register the Dapr client:

builder.Services.AddDaprClient();

You can then retrieve the DaprClient instance using dependency injection:

public class ExampleService(DaprClient daprClient)
{
    public async Task CallServiceAsync()
    {
        var response = await daprClient.InvokeMethodAsync<Response>(
            HttpMethod.Get,
            "exampleproject",
            "api/data");
    }
}

Service-to-service invocation

Dapr enables service-to-service invocation using the app ID. When you add a Dapr sidecar to a project, you can invoke methods on that service using the app ID:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprClient();
  
var app = builder.Build();
  
app.MapGet("/call-service", async (DaprClient daprClient) =>
{
    var result = await daprClient.InvokeMethodAsync<string>(
        HttpMethod.Get,
        "exampleproject",
        "api/data");
  
    return Results.Ok(result);
});
  
app.Run();

For more information on Dapr service invocation, see Dapr service invocation.

Configure Dapr state stores

The Aspire Dapr integration supports adding Dapr state store components. Use the AddDaprStateStore method to register a state store and reference it from your services:

var builder = DistributedApplication.CreateBuilder(args);
  
var stateStore = builder.AddDaprStateStore("statestore");
  
builder.AddProject<Projects.ExampleProject>("exampleproject")
       .WithDaprSidecar()
       .WithReference(stateStore);
  
// After adding all resources, run the app...

Configure an actor state store

To configure a state store as an actor state store (required by Dapr actors), add the actorStateStore metadata entry to your component file. Create a components directory in your app host and add a component YAML file:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: statestore
spec:
  type: state.redis
  version: v1
  metadata:
    - name: redisHost
      value: localhost:6379
    - name: actorStateStore
      # Setting actorStateStore to "true" designates this state store
      # as the actor state store. Dapr actors require exactly one state
      # store to be configured with this flag.
      value: "true"

Reference the component directory in your AppHost using WithDaprSidecar options:

var builder = DistributedApplication.CreateBuilder(args);
  
builder.AddProject<Projects.ActorService>("actorservice")
       .WithDaprSidecar(new DaprSidecarOptions
       {
           ResourcesDirectory = "./components"
       });
  
// After adding all resources, run the app...

Deploy with Azure Container Apps

The Aspire Dapr Community Toolkit integration configures Dapr sidecars for local development. When deploying to Azure Container Apps (ACA), Dapr sidecar settings are part of the container app configuration and must be preserved on each deployment.

Caution

When you redeploy a container app that previously had Dapr enabled, Azure Container Apps does not automatically retain Dapr settings from the previous deployment. If Dapr appears disabled in the Azure portal after redeployment, re-enable it by configuring the Dapr settings in the ACA environment or by using PublishAsAzureContainerApp with explicit Dapr configuration.

To ensure Dapr settings are preserved on Azure Container Apps deployments, configure the sidecar explicitly using PublishAsAzureContainerApp:

var builder = DistributedApplication.CreateBuilder(args);
  
builder.AddProject<Projects.ExampleProject>("exampleproject")
       .WithDaprSidecar()
       .PublishAsAzureContainerApp((infra, app) =>
       {
           // Enable Dapr on the container app and set the app ID
           app.Configuration.Dapr = new()
           {
               IsEnabled = true,
               AppId = "exampleproject",
               AppPort = 8080,
           };
       });
  
// After adding all resources, run the app...

For more information on customizing Azure Container Apps resources, see Configure Azure Container Apps.