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
builderIOutboxBuilderThe 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
builderIOutboxBuilderThe outbox builder.
isLeaderCheckFunc<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.