plan-forge dapr.instructions.md

.NET Dapr Patterns

Standard: Dapr v1.14+ with .NET Aspire / Docker Compose
Packages: Dapr.AspNetCore, Dapr.Client, Dapr.Workflow
Cross-ref: messaging.instructions.md covers pub/sub message schemas and CloudEvents in detail

---

Sidecar Architecture

Non-Negotiable Rules

• NEVER call external services directly — always go through the Dapr sidecar
• NEVER hardcode Dapr HTTP/gRPC ports — use DAPR_HTTP_ENDPOINT / DAPR_GRPC_ENDPOINT env vars
• ALWAYS scope components to the services that need them
• ALWAYS use the typed DaprClient — never raw HTTP to localhost:3500

DaprClient Registration

// Program.cs — register DaprClient with DI
var builder = WebApplication.CreateBuilder(args);

// Standard registration
builder.Services.AddDaprClient();

// NativeAOT-compatible registration (source-generated JSON)
builder.Services.AddDaprClient(clientBuilder =>
{
    clientBuilder.UseJsonSerializationOptions(new JsonSerializerOptions
    {
        TypeInfoResolver = AppJsonContext.Default,
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });
});

var app = builder.Build();
app.MapSubscribeHandler(); // Required for pub/sub subscriptions

Docker Compose Sidecar Pattern

# Each service gets its own Dapr sidecar container
my-service:
  build: ./MyService
  environment:
    - DAPR_HTTP_ENDPOINT=http://my-service-sidecar:3500
    - DAPR_GRPC_ENDPOINT=http://my-service-sidecar:50001

my-service-sidecar:
  image: daprio/daprd:1.14.4
  command:
    - ./daprd
    - --app-id=my-service
    - --app-port=8080
    - --dapr-http-port=3500
    - --dapr-grpc-port=50001
    - --resources-path=/components
    - --log-level=info
  volumes:
    - ./dapr/components:/components
  network_mode: service:my-service   # Share network namespace

# Placement service (required for actors/workflows)
dapr-placement:
  image: daprio/dapr:1.14.4
  command: ["./placement", "--port", "50006"]

---

State Management