Commit the change and the message together.
outbox-kit is a small .NET library for the transactional outbox pattern on EF Core and PostgreSQL, with an idempotent consumer.
await db.SaveChangesAsync();
// committed
await broker.PublishAsync(message);
// process dies here: the change exists,
// nobody was toldTwo timelines, one crash.
The first loses a message without raising any error. The second crashes in the worst possible spot and still ends with each effect applied once.
Buttons work with the keyboard. Left and right arrow keys move between steps.
Three calls.
AddOutbox() in OnModelCreating adds the outbox and inbox to your model. After that:
db.Enqueue(type, payload) adds a row to outbox_messages. The same SaveChanges saves it, so the change and the message commit together or not at all.
OutboxDispatcher.RunOnceAsync() locks a batch with FOR UPDATE SKIP LOCKED, calls your IOutboxPublisher, marks the rows processed and commits. Several dispatchers can run at once without publishing the same row twice.
db.HandleOnceAsync(consumer, messageId, handler) records the message id in inbox_messages and runs your handler in one transaction. A redelivered message is skipped.
protected override void OnModelCreating(ModelBuilder b) => b.AddOutbox();
// when you change something
order.MarkPaid();
db.Enqueue("order.paid", JsonSerializer.Serialize(new { order.Id }));
await db.SaveChangesAsync();
// in a background loop
var dispatcher = new OutboxDispatcher(db, myPublisher);
while ((await dispatcher.RunOnceAsync()).Claimed > 0) {}
// in the consumer
await db.HandleOnceAsync("billing", messageId, async ct => { /* change your own tables */ });25 tests against a real Postgres.
dotnet test needs Docker: it starts postgres:17-alpine with Testcontainers. The broker is a stand-in that writes to a table on its own connection, so a rollback cannot erase a publish.
An independent audit found a real bug: a publisher timeout was never counted as an attempt, so a message could be republished forever. It is fixed and has its own test below. The decisions that came out of it are in docs/decisions.md.
The chaos test
A separate process publishes three messages and is killed with Environment.FailFast before the commit. That call skips finally blocks, so nothing gets to clean up. A second worker then finishes the job.
- 20
- messages processed, none lost
- 23
- publishes reached the broker
- 3
- of those were duplicates
- 1
- effect per message after the consumer replayed every one twice
The duplicates are the point. The outbox gives you at-least-once delivery. The inbox is what turns that into one effect per message.
Writing
- Enqueue_is_saved_in_the_same_transaction_as_the_business_change
- The business row and the outbox row both exist after one SaveChanges.
- A_failing_save_leaves_neither_the_business_row_nor_the_message
- A payload Postgres rejects fails the whole save: no business row, no message.
Dispatching
- Dispatcher_publishes_pending_messages_in_batches_and_marks_them_processed
- 25 pending messages go out in batches of 10, 10 and 5, and all 25 end up processed.
- Three_dispatchers_running_at_once_never_publish_the_same_message
- Three dispatchers running at once publish each of 40 messages exactly once, and more than one of them handled messages, so the runs overlapped.
- A_dispatcher_skips_rows_another_transaction_has_locked_instead_of_waiting
- Another transaction holds the locks of five rows. The dispatcher publishes the other five without waiting, which plain FOR UPDATE would not do.
- RunOnce_tells_a_batch_that_all_failed_apart_from_an_empty_queue
- A run where every publish fails reports Failed and Claimed of 3. An empty queue reports Claimed of 0.
- Options_that_would_never_make_progress_are_rejected
- A batch size below 1 or MaxAttempts below 1 throws when the dispatcher is created (three cases).
Failing
- A_poison_message_is_retried_then_parked_and_does_not_block_the_others
- A message the broker keeps rejecting is parked after three attempts. The other four still go out.
- A_publisher_timeout_counts_as_a_failed_attempt_and_does_not_stall_the_queue
- A TaskCanceledException from the publisher counts as one attempt. The other four go out and nothing is published twice. This is the test for the bug the audit found.
- Cancelling_the_run_itself_still_rolls_back_and_throws
- Cancelling the token you passed to RunOnceAsync aborts the run and rolls it back.
The caller's context
- RunOnce_does_not_save_unrelated_pending_changes_on_the_callers_context
- A row you added but did not save stays unsaved after a run, and still tracked as yours.
- A_stale_tracked_row_cannot_make_the_dispatcher_lose_an_attempt
- Two contexts failing the same row in turn count three attempts, not two.
- The_change_tracker_does_not_grow_with_the_number_of_runs
- After six runs over 30 messages the context tracks nothing.
- Both_throw_a_clear_error_when_a_transaction_is_already_open
- RunOnceAsync and HandleOnceAsync throw InvalidOperationException if the context already has a transaction.
- HandleOnce_refuses_a_context_that_already_has_pending_changes
- HandleOnceAsync throws instead of committing changes it did not make.
- Dispatcher_and_consumer_work_on_a_context_with_EnableRetryOnFailure
- Both go through the EF execution strategy, so a retrying context works.
- Dispatcher_and_consumer_work_with_a_custom_default_schema
- With HasDefaultSchema the raw SQL still finds the tables.
Consuming
- Idempotent_consumer_runs_the_handler_once_per_message_even_when_called_twice
- The second call for the same message id is skipped and the effect exists once.
- Idempotent_consumer_keeps_consumers_separate
- The same message id is handled once per consumer name, not once overall.
- A_handler_that_throws_records_nothing_so_the_message_can_be_retried
- A failed handler leaves nothing in the inbox, so the retry runs it again.
- A_failed_handler_can_be_retried_on_the_same_context_without_applying_the_effect_twice
- After a failure the handler's added rows are dropped from the tracker, so a retry applies the effect once.
- A_failed_handler_also_reverts_modified_entities
- Entities the handler modified go back to their original values.
Crashing
- Killing_the_process_between_publish_and_commit_loses_nothing_and_applies_each_effect_once
- The chaos test above. A real process, a real kill, a second worker to finish.
What it does not do.
This is a short reference implementation (about 300 lines), not a replacement for MassTransit or Wolverine. Read these before you copy it.
- PostgreSQL only.
- It relies on FOR UPDATE SKIP LOCKED, jsonb and ON CONFLICT DO NOTHING. Supporting SQL Server would roughly double the SQL and the tests.
- The publish holds the locks.
- The publish call runs inside the locking transaction, so a slow broker means a long transaction. Fine for modest volume. For more, move the lock to a short lease and publish outside the transaction.
- No ordering guarantee at all.
- created_at is stamped when you call Enqueue, not when the transaction commits, so a message can commit after a later one. Parallel dispatchers and retries reorder further. If order matters, put a sequence number in the payload and have the consumer check it.
- Your own transaction is not welcome.
- RunOnceAsync and HandleOnceAsync open their own transaction and throw if the context already has one. HandleOnceAsync also throws if the context has pending changes.
- Retries can duplicate.
- Both go through the EF execution strategy, so EnableRetryOnFailure works. After a transient failure a dispatcher run repeats and may publish a row again, so the consumer has to be idempotent anyway.
- The payload is normalized.
- It is stored as jsonb, so Postgres changes key order and whitespace and collapses duplicate keys. Do not rely on byte-for-byte equality with what you enqueued.
- No cleanup, no metrics.
- You will want a job that deletes old rows from outbox_messages and inbox_messages.
- Not benchmarked.
- There is no throughput claim on this page because there is no measurement behind one.
- Not on NuGet.
- Clone the repository to use it.