outbox-kit

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 told
Swap the two lines and you get the opposite failure: the message goes out for a change that never committed.

Two 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.

Diagram ready. Press Play.

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.