feat: EF-core-oubox-support-for-Dapr

[Psingle20]

Description

Adds convenience APIs on Dapr.Client that make it easier to compose state transactions engaging the Dapr runtime's native transactional outbox feature (state store component configured with outboxPublishPubsub and related metadata).

Scope-trimmed from the original submission per reviewer feedback — the Dapr.EntityFrameworkCore.Outbox package I initially included will be published as a standalone community NuGet instead, since it's a userland alternative to the runtime outbox rather than an extension of it.

Changes

• DaprOutboxMetadata — canonical metadata key constants used by the state store outbox (outbox.projection, outbox.pubsubname, outbox.topic, cloudevent.id, cloudevent.type, cloudevent.source, cloudevent.datacontenttype, cloudevent.subject, etc.). Callers reference constants instead of stringly-typed keys.
• StateTransactionRequestExtensions — fluent helpers on StateTransactionRequest:
  • WithOutboxProjection(pubsubName, topic, payload?, contentType?) — attaches the outbox projection metadata to a state entry.
  • WithCloudEventMetadata(...) — sets cloudevent.* overrides on an entry.
• OutboxTransactionBuilder — small composer that enforces the invariant that the state entry and its outbox projection share the same key, so a single ExecuteStateTransactionAsync call publishes the message atomically with the state write.

Testing

• 22 new unit tests in test/Dapr.Client.Test/:
  • DaprOutboxMetadataTests — validates the key constants match Dapr's runtime contract.
  • StateTransactionRequestExtensionsTests — covers default content type, metadata merging, and null-argument guards.
  • OutboxTransactionBuilderTests — enforces the state-entry / projection key-match invariant, verifies the produced request shape, and rejects mismatched configurations.
• Full Dapr.Client.Test suite is green: 283 / 283 passing on net10.0.

Issue reference

Refs #1494

Checklist

• Code compiles correctly (net8.0 / net9.0 / net10.0)
• Created/updated tests (22 new, 283 total green)
• Extended the documentation (XML doc comments on all new public APIs)

[Psingle20]

Hi @WhitWaldo can you review this ?

[WhitWaldo]

First of all, thank you for putting this together especially in response to a long-standing ask from the community.

I don't mind reviewing and likely approving the extensions to simplify setting up the state transaction requests from the DaprClient side. I think those are certainly worthwhile and improve the developer experience in the current approach.

But with regards to the Dapr.EntityFrameworkCore.Outbox package, I'm not inclined to accept it. The transactional outbox is an operation handled entirely by the runtime using the components registered with it. The whole of the SDK is to facilitate the means of engaging with the runtime, not to emulate or replace whole pieces of it to run locally. As yours is a standalone outbox implementation that takes no dependency on the Dapr runtime except to persist the state and instead shifts the entire output responsibility to the SDK, it simply does not belong in this repository.

That said, I can certainly imagine a scenario where it might be a useful feature. I would instead urge you to consider publishing the package to NuGet yourself. Reach out to @marcduiker on Discord and schedule some time to show off your work and promote it to the larger Dapr community - I'm sure there's someone that can use that.

With regards to this PR though, I regret that I cannot accept it as provided. If you can instead remove everything but the Dapr.Client changes and the corresponding tests, I'd be happy to review and get those merged for one of the future 1.18 patch releases.

[Psingle20]

First of all, thank you for putting this together especially in response to a long-standing ask from the community.

I don't mind reviewing and likely approving the extensions to simplify setting up the state transaction requests from the DaprClient side. I think those are certainly worthwhile and improve the developer experience in the current approach.

But with regards to the Dapr.EntityFrameworkCore.Outbox package, I'm not inclined to accept it. The transactional outbox is an operation handled entirely by the runtime using the components registered with it. The whole of the SDK is to facilitate the means of engaging with the runtime, not to emulate or replace whole pieces of it to run locally. As yours is a standalone outbox implementation that takes no dependency on the Dapr runtime except to persist the state and instead shifts the entire output responsibility to the SDK, it simply does not belong in this repository.

That said, I can certainly imagine a scenario where it might be a useful feature. I would instead urge you to consider publishing the package to NuGet yourself. Reach out to @marcduiker on Discord and schedule some time to show off your work and promote it to the larger Dapr community - I'm sure there's someone that can use that.

With regards to this PR though, I regret that I cannot accept it as provided. If you can instead remove everything but the Dapr.Client changes and the corresponding tests, I'd be happy to review and get those merged for one of the future 1.18 patch releases.

Thanks for the thoughtful review and for drawing a clear line on where the SDK ends and userland begins. That reasoning makes sense: the runtime already owns the transactional outbox as a first-class capability via the state store components, and the EF Core package I put together is really an alternative for users whose aggregates live outside a Dapr state store, rather than an extension of the runtime feature. Different pattern, different home.

I've force-pushed the branch back to just the [Dapr.Client] and made the required changes.

I'll spin the EF Core work out to its own repo + NuGet and reach out to @marcduiker on Discord to see about promoting it through the community channel. Appreciate the pointer.

[marcduiker]

Hey @Psingle20! Yeah, this is a great topic for a community call. my Discord handle is marcduiker.

[Psingle20]

Hey @Psingle20! Yeah, this is a great topic for a community call. my Discord handle is marcduiker.

Hi @marcduiker, sorry for the late reply. I’ve been caught up with work and haven’t been keeping well. I’ll try to reach out around the weekend.

[Psingle20]

Hi @marcduiker have sent you a friend request my discord handle is Prachpit . Let me know how i can get involved with community!

[Copilot]

Pull request overview

This PR adds first-class helper APIs in Dapr.Client to make it easier and safer to compose state transactions that leverage Dapr’s native transactional outbox behavior via state-store metadata, along with unit tests validating the new helpers.

Changes:

• Introduces DaprOutboxMetadata constants for well-known outbox / CloudEvent metadata keys.
• Adds StateTransactionRequestExtensions to mark requests as outbox projections and to apply CloudEvent metadata overrides without mutating the source request.
• Adds OutboxTransactionBuilder to compose ordered state/projection request pairs for ExecuteStateTransactionAsync, plus unit tests for all new APIs.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Dapr.Client/DaprOutboxMetadata.cs	Adds public constants for outbox-related metadata keys.
src/Dapr.Client/StateTransactionRequestExtensions.cs	Adds non-mutating helpers to merge projection + CloudEvent metadata into StateTransactionRequest.
src/Dapr.Client/OutboxTransactionBuilder.cs	Adds a fluent builder that emits correctly ordered state + projection transaction requests.
test/Dapr.Client.Test/DaprOutboxMetadataTests.cs	Adds tests that lock metadata constant values to the runtime wire contract.
test/Dapr.Client.Test/StateTransactionRequestExtensionsTests.cs	Adds tests covering non-mutation, metadata merge behavior, and null-guarding.
test/Dapr.Client.Test/OutboxTransactionBuilderTests.cs	Adds tests for builder ordering, pairing behavior, and argument validation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Psingle20]

Hi @WhitWaldo I think this is good to go let me know if anything else required

[WhitWaldo]

Looks good - thank you for taking the time to build and contribute this!