Table of Contents

Class OutboxBuilderProcessingGateExtensions

Namespace
Microsoft.Extensions.DependencyInjection
Assembly
Excalibur.Outbox.dll

Extension methods for adding a custom, delegate-based processing gate to IOutboxBuilder.

public static class OutboxBuilderProcessingGateExtensions
Inheritance
OutboxBuilderProcessingGateExtensions
Inherited Members

Remarks

The leader-election-backed WithLeaderElection() overload — gated on the atomic, fencing-token-carrying leadership snapshot — lives in the Excalibur.LeaderElection package. Excalibur.Outbox takes no dependency on leader election; this class provides only the advisory, delegate-based gate for consumers who want custom gating without leader election.

Methods

AsSingleWriter(IOutboxBuilder)

Asserts that exactly one process drains this outbox, opting the drain out of leadership fencing even when a leader election is registered for other resources.

public static IOutboxBuilder AsSingleWriter(this IOutboxBuilder builder)

Parameters

builder IOutboxBuilder

The outbox builder.

Returns

IOutboxBuilder

The builder for fluent chaining.

Remarks

Fencing is on by default for a framework-protected outbox: registering a leader election is the multi-instance signal, so the drain is fenced. On stores that record the fencing high-water durably (PostgreSQL, Oracle, SQL Server, MongoDB) a superseded leader cannot claim or complete messages it no longer owns: each keeps a dedicated fence record that cleanup never deletes, so the mark survives a purge of sent rows. Stores that cannot express an atomic high-water do not implement the fenced contract at all, and startup refuses rather than degrading silently. This method is the explicit, positive topology assertion — "I am the single active writer, I own the exactly-once guarantee" — for a deployment where a leader election is registered for other resources (leases, scheduled jobs) but exactly one process drains this outbox.

The opt-out is observable: the outbox logs a startup warning that it is running unfenced by single-active-writer opt-out. Enabling this in a genuinely multi-writer deployment reopens the split-brain window fencing exists to close, so it must reflect a real single-active-writer topology.

WithLeaderElection(IOutboxBuilder, Func<IServiceProvider, bool>)

Configures the outbox background service to skip processing when the provided gate returns false.

public static IOutboxBuilder WithLeaderElection(this IOutboxBuilder builder, Func<IServiceProvider, bool> isLeaderCheck)

Parameters

builder IOutboxBuilder

The outbox builder.

isLeaderCheck Func<IServiceProvider, bool>

A factory delegate that, given an IServiceProvider, returns true when this instance should process outbox messages.

Returns

IOutboxBuilder

The builder for fluent chaining.

Examples

services.AddExcalibur(x => x.AddOutbox(outbox =>
{
    outbox.UseInMemory()
          .WithLeaderElection(sp => MyCustomGateCheck(sp))
          .EnableBackgroundProcessing();
}));

Remarks

When registered, the Excalibur.Outbox.Outbox.OutboxBackgroundService checks ShouldProcess before each polling cycle. If the gate returns false, the cycle is skipped.

This overload is advisory only — the supplied predicate carries no fencing token, so it must not be wired to a bare leadership bool for split-brain-safe gating. Prefer the leader-election package's parameterless WithLeaderElection() overload, which gates on the atomic leadership snapshot and fails closed. Use this overload only for a genuinely custom gate that is not leader-election-backed.