Tutorial

This tutorial uses the runnable examples in the .NET SDK repository to demonstrate the main capabilities of Dapr.Messaging. Each part includes the implementation pattern and the corresponding unit and integration testing approach.

The examples use .NET 8, .NET 9, or .NET 10 and require Dapr runtime 1.18 or later. The unit tests run without Dapr, Docker, or a message broker. The integration tests use Dapr.Testcontainers to run a real Dapr sidecar and Redis pub/sub component, which is the recommended way to verify delivery behavior in an application.

Tutorial content

Part 1: Publish events: Typed events, CloudEvent metadata, bulk publishing, and raw payloads.
Part 2: Declarative streaming subscriptions: Source-generated handlers with explicit success, retry, and drop acknowledgements.
Part 3: Content-based routing and dead-letter topics: CEL matching rules, priorities, metadata, and dead-letter handling.
Part 4: Bulk subscriptions: High-throughput delivery with bounded batch size and wait duration.
Part 5: gRPC AppCallback push: Sidecar-initiated gRPC delivery for applications that expose a gRPC port.
Part 6: HTTP push subscriptions: Generated /dapr/subscribe discovery and custom HTTP routes.
Part 7: Dynamic streaming subscriptions: Imperative runtime subscriptions with supervision, cancellation, and reconnect behavior.

Testing pattern

Keep message-handling decisions in ordinary C# handlers so they can be tested directly. The example unit tests construct a TopicContext, invoke HandleAsync, and assert the returned TopicResponseAction for valid, invalid, and transient inputs.

Add integration tests for the infrastructure boundary. The examples create a PubSubHarness, configure the application with the harness’s dynamically assigned Dapr endpoints, publish real events, and wait for observable processing results. Use bounded timeouts, IAsyncLifetime cleanup, and a test log sink rather than sleeps alone when validating asynchronous delivery.

Prerequisites

.NET SDK 8, 9, or 10
Dapr CLI and a Dapr environment
Dapr runtime 1.18 or later for streaming subscriptions
Docker or another container runtime for integration tests
The Dapr.Messaging package

When using the SDK repository directly, the examples reference the local SDK projects. In an application, install the published Dapr.Messaging package instead.

Part 1: Publishing Publish typed, bulk, metadata-rich, and raw events with IDaprPublishSubscribeClient Learn more → Part 2: Streaming Consume pub/sub events over an application-initiated streaming gRPC connection Learn more → Part 3: Routing and DLQs Route messages with CEL expressions and handle rejected messages with a dead-letter topic Learn more → Part 4: Bulk subscriptions Configure bounded bulk delivery for high-throughput pub/sub consumers Learn more → Part 5: AppCallback push Receive pub/sub events through sidecar-initiated gRPC AppCallback calls Learn more → Part 6: HTTP subscriptions Expose generated HTTP subscription discovery and custom event routes Learn more → Part 7: Dynamic streaming Open imperative streaming subscriptions for topics chosen at runtime Learn more →

Last modified September 13, 2026: Updated documentation to include tutorial documentation going through implementation, unit and integration testing for Dapr.Messaging (8c51cf06b)