Messaging

Dapr.Messaging is the unified Dapr Publish/Subscribe messaging SDK for .NET. It brings all Dapr pub/sub functional modes—event publishing, streaming pull subscriptions, programmatic gRPC push subscriptions, and HTTP subscriptions—together into a single, modern package family.

Rather than fragmenting pub/sub across Dapr.Client and Dapr.AspNetCore, Dapr.Messaging provides a clean, cohesive programming model built on top of modern .NET fundamentals: Roslyn source generators for reflection-free dispatch, compile-time Roslyn analyzers, and the standard Microsoft.Extensions.Options pattern.

<ItemGroup>
  <PackageReference Include="Dapr.Messaging" Version="..." />
</ItemGroup>

What changed

The Dapr .NET SDK originally distributed messaging capabilities across multiple packages: Dapr.Client provided basic publish and dynamic streaming pull methods, while Dapr.AspNetCore handled controller-based and minimal API push subscriptions via HTTP endpoints.

Dapr.Messaging unifies and modernizes this architecture:

1. Unified publishing and subscribing: Publish events with IDaprPublishSubscribeClient (including single events, raw byte streams, and bulk publishing) and author subscribers using a single ITopicHandler<TMessage> interface.
2. Three unified delivery modes: Subscriptions support DeliveryMode.Streaming (application-initiated bidirectional gRPC stream with backpressure), DeliveryMode.Programmatic (sidecar-to-app gRPC AppCallback push), and DeliveryMode.Http (sidecar-to-app HTTP push via /dapr/subscribe), all configured through the same [DaprTopic] attribute.
3. Source generators eliminate reflection: The Dapr.Messaging.Generators source generator inspects [DaprTopic] handlers at compile time and emits typed dispatchers, subscriber registries, and dependency injection wiring. No runtime reflection or runtime code generation is performed on the invocation path.
4. AOT and trimming considerations: Handler discovery and dispatch registration are generated at compile time, but the current generated subscriber dispatchers use runtime System.Text.Json metadata. Native AOT and trimming scenarios require explicit validation with the target SDK version.
5. Roslyn analyzers and diagnostics: The SDK includes compile-time analyzers (DAPR1610–DAPR1617) that catch misconfigurations directly in your IDE as you write code:
   • DAPR1610 (Error): Conflicting delivery modes on the same topic.
   • DAPR1611 (Error): [DaprTopic] class not implementing ITopicHandler<TMessage>.
   • DAPR1612 (Warning): Unregistered message type in Native AOT compilation.
   • DAPR1613 (Warning): Missing app.MapDaprMessaging() for programmatic subscriptions (with CodeFix).
   • DAPR1614 (Warning): Direct invocation of internal DaprMessagingRegistration.
   • DAPR1615 (Warning): Endpoint mapping present without matching topic subscribers.
   • DAPR1616 (Warning): [DaprTopic] feature enabled without companion properties.
   • DAPR1617 (Warning): Ignored [DaprTopic] properties for the selected delivery mode or feature.
6. Standard options and simplified DI: Uses IOptions<DaprMessagingOptions> and a single services.AddDaprMessaging() method that registers options, the publishing client, source-generated subscriber dispatchers, and required hosting services in a single atomic operation.

Comparison with legacy pub/sub approaches

Core concepts

• Tutorial: Dapr.Messaging by example: Seven runnable examples covering publishing, streaming, routing, bulk subscriptions, gRPC push, HTTP push, dynamic streaming, and their unit and integration testing patterns.
• Publish events how-to: Step-by-step guide to publishing JSON events, CloudEvents, raw payloads, and bulk message batches using IDaprPublishSubscribeClient.
• Subscribe to topics how-to: Step-by-step guide to authoring ITopicHandler<TMessage> subscribers, choosing delivery modes with [DaprTopic], compile-time source generation, dynamic streaming subscriptions, and compiler diagnostics.
• Configuration and usage guide: Lifetime management, DI options configuration, advanced features (bulk pub/sub, dead-letter topics, CEL routing), and AOT/trimming considerations.

Next steps

• Tutorial: Dapr.Messaging by example
• How-To: Publish events with IDaprPublishSubscribeClient
• How-To: Author subscriptions and handle topic messages
• Dapr Messaging configuration and usage reference
• Dapr Pub/Sub building block overview