Tutorial: Dapr.Messaging by example on Dapr Docs

Part 1: Publish events with Dapr.Messaging

Mon, 01 Jan 0001 00:00:00 +0000

The publishing example introduces IDaprPublishSubscribeClient, the publishing API in Dapr.Messaging.

Register the client

AddDaprMessaging() registers the client with dependency injection:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprMessaging();
var app = builder.Build();

Inject IDaprPublishSubscribeClient into an endpoint, service, or background worker. The client is intended to be reused rather than created for every message.

Publish typed events

app.MapPost("/orders", async (
 OrderPlaced order,
 IDaprPublishSubscribeClient client,
 CancellationToken cancellationToken) =>
{
 await client.PublishEventAsync(
 "pubsub",
 "orders",
 order,
 cancellationToken);

 return Results.Accepted($"/orders/{order.OrderId}");
});

Typed payloads are serialized as JSON and published as Dapr CloudEvents. Pass the request cancellation token through the SDK call.

Part 2: Declarative streaming subscriptions

Mon, 01 Jan 0001 00:00:00 +0000

The streaming example shows the recommended declarative subscription model for fixed topics.

Define a handler

Implement ITopicHandler<TMessage> and decorate the handler with DaprTopic:

[DaprTopic("pubsub", "orders", Delivery = DeliveryMode.Streaming)]
public sealed class OrderProcessingHandler : ITopicHandler<OrderPlaced>
{
 public Task<TopicResponseAction> HandleAsync(
 OrderPlaced order,
 TopicContext context,
 CancellationToken cancellationToken)
 {
 if (order.Quantity <= 0 || string.IsNullOrWhiteSpace(order.ItemSku))
 {
 return Task.FromResult(TopicResponseAction.Drop);
 }

 if (order.ItemSku.StartsWith("RETRY-", StringComparison.OrdinalIgnoreCase))
 {
 return Task.FromResult(TopicResponseAction.Retry);
 }

 return Task.FromResult(TopicResponseAction.Success);
 }
}

Success acknowledges the message, Retry requests redelivery for a transient failure, and Drop rejects an invalid or poison message. The handler also receives TopicContext, which contains the pub/sub name, topic, message ID, headers, and metadata.

Part 3: Content-based routing and dead-letter topics

Mon, 01 Jan 0001 00:00:00 +0000

The routing example uses multiple generated subscriptions to route shipments and handle rejected messages.

Add CEL matching rules

Match is evaluated against the CloudEvent. Priority controls rule ordering, with lower values evaluated first:

[DaprTopic(
 "pubsub",
 "express-shipments",
 Match = "event.data.priorityTier == 'express'",
 Priority = 1,
 DeadLetterTopic = "deadletter-shipments")]
[DaprTopicMetadata("routingType", "express-tier")]
public sealed class ExpressShippingHandler : ITopicHandler<ShipmentPackage>
{
 public Task<TopicResponseAction> HandleAsync(
 ShipmentPackage shipment,
 TopicContext context,
 CancellationToken cancellationToken)
 {
 return Task.FromResult(
 shipment.WeightKg <= 0
 ? TopicResponseAction.Drop
 : TopicResponseAction.Success);
 }
}

The example adds an international rule using event.data.destinationCountry != 'US' and a priority-10 catch-all handler for standard domestic shipments. DaprTopicMetadata adds custom key-value data to the generated subscription manifest.

Part 4: Bulk subscriptions

Mon, 01 Jan 0001 00:00:00 +0000

The bulk subscription example combines bulk publishing with a subscription configured for high-throughput ingestion.

Configure batching

Set BulkSubscribe and its limits on the topic attribute:

[DaprTopic(
 "pubsub",
 "telemetry",
 BulkSubscribe = true,
 MaxMessagesCount = 50,
 MaxAwaitDurationMs = 500)]
public sealed class TelemetryBulkHandler : ITopicHandler<DeviceTelemetry>
{
 public Task<TopicResponseAction> HandleAsync(
 DeviceTelemetry reading,
 TopicContext context,
 CancellationToken cancellationToken)
 {
 if (reading.TemperatureCelsius < -273.15 ||
 reading.HumidityPercent is < 0 or > 100)
 {
 return Task.FromResult(TopicResponseAction.Drop);
 }

 return Task.FromResult(TopicResponseAction.Success);
 }
}

MaxMessagesCount bounds the batch size and MaxAwaitDurationMs bounds how long Dapr waits before delivering a partial batch. Choose values based on throughput, latency, and broker behavior. The handler remains responsible for the individual message decision.

Part 5: gRPC AppCallback push subscriptions

Mon, 01 Jan 0001 00:00:00 +0000

The AppCallback example uses DeliveryMode.Programmatic for sidecar-to-application gRPC push.

Define a programmatic subscriber

[DaprTopic("pubsub", "payments", Delivery = DeliveryMode.Programmatic)]
public sealed class PaymentProcessingHandler : ITopicHandler<PaymentReceived>
{
 public Task<TopicResponseAction> HandleAsync(
 PaymentReceived payment,
 TopicContext context,
 CancellationToken cancellationToken)
 {
 return Task.FromResult(
 payment.Amount <= 0
 ? TopicResponseAction.Drop
 : TopicResponseAction.Success);
 }
}

In this mode Dapr initiates the gRPC call to the application’s AppCallback service. Unlike streaming subscriptions, the app must expose a reachable gRPC port.

Map the generated endpoint

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprMessaging();

var app = builder.Build();
app.MapDaprMessaging();
app.Run();

MapDaprMessaging() exposes the generated AppCallback gRPC service used by the sidecar to list subscriptions and deliver events. Run the application with an app port and gRPC protocol, for example:

Part 6: HTTP push subscriptions

Mon, 01 Jan 0001 00:00:00 +0000

The HTTP subscription example shows DeliveryMode.Http for applications that use normal HTTP ingress or reverse proxies.

Define a routed handler

[DaprTopic(
 "pubsub",
 "invoices",
 Delivery = DeliveryMode.Http,
 Route = "api/events/invoices")]
public sealed class InvoiceProcessingHandler : ITopicHandler<InvoiceGenerated>
{
 public Task<TopicResponseAction> HandleAsync(
 InvoiceGenerated invoice,
 TopicContext context,
 CancellationToken cancellationToken)
 {
 return Task.FromResult(
 invoice.TotalAmount <= 0
 ? TopicResponseAction.Drop
 : TopicResponseAction.Success);
 }
}

Map the generated routes

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprMessaging();

var app = builder.Build();
app.MapDaprMessaging();
app.Run();

The generated mapping exposes GET /dapr/subscribe for Dapr to discover subscriptions and maps POST /api/events/invoices for the topic’s CloudEvents. The route is generated from the Route property; it does not need a separate controller or action.

Part 7: Dynamic streaming subscriptions

Mon, 01 Jan 0001 00:00:00 +0000

The dynamic streaming example uses SubscribeAsync when topics or subscription lifetime cannot be fixed at compile time.

Register the client and worker

builder.Services.AddDaprPubSubClient();
builder.Services.AddHostedService<DynamicSubscriberWorker>();

The worker opens a subscription to a runtime-selected topic:

var options = new DaprSubscriptionOptions(
 new MessageHandlingPolicy(
 TimeoutDuration: TimeSpan.FromSeconds(10),
 DefaultResponseAction: TopicResponseAction.Retry))
{
 DeadLetterTopic = "tenant-events-dlq",
 ErrorHandler = exception =>
 {
 logger.LogWarning("Subscription error: {Message}", exception.Message);
 return Task.CompletedTask;
 }
};

await using var subscription = await client.SubscribeAsync(
 "pubsub",
 "tenant-events",
 options,
 HandleDynamicMessageAsync,
 stoppingToken);

await ((IDaprSubscription)subscription).Completion.WaitAsync(stoppingToken);

SubscribeAsync returns an async-disposable subscription and an IDaprSubscription.Completion task. A supervisor can await completion, log faults, delay, and open a new subscription. Always dispose the subscription and honor the host cancellation token.