Agent guide
OpinionatedEventing is new and opinionated. AI assistants often guess its API from MassTransit, NServiceBus or MediatR. Those guesses are usually wrong. Read this page before writing code that uses the library.
Other pages for agents: API cheat sheet, Which package do I need?, Recipes, Coming from MassTransit / NServiceBus / MediatR, Instruction templates. Machine-readable indexes: /llms.txt and /llms-full.txt.
Design rules
- There is no direct publish path.
IPublisherwrites to the outbox table in the caller's transaction. A background worker forwards it to the broker. Never inject a broker client (ServiceBusClient,IConnection, ...) to publish. - Commands and events are different things.
ICommand: "please do X". Exactly oneICommandHandler<T>per command type. A second registration throwsInvalidOperationExceptionat startup.IEvent: "X happened". Zero or moreIEventHandler<T>.
- Send commands with
SendCommandAsync, publish events withPublishEventAsync. Both live onIPublisher. - Delivery is at-least-once. Handlers must tolerate duplicates. See Idempotency.
- Aggregates raise events, they do not publish. Extend
AggregateRootand callRaiseDomainEvent(...). TheDomainEventInterceptorwrites the outbox rows duringSaveChangesAsync. Never injectIPublisherinto an aggregate. - One
SaveChangesAsynccommits business data and outbox rows together. Do not call it inside aggregate methods. - Handler classes are registered by scanning. Use
AddHandlersFromAssemblies. Do not registerICommandHandler<T>/IEventHandler<T>by hand. - Sagas are registered explicitly.
AddSaga<T>()for orchestrators,AddSagaParticipant<T>()for choreography participants. Both register the underlying event subscriptions for you. - Transport is a DI choice. Handler, aggregate and saga code never changes between Azure Service Bus and RabbitMQ.
- Name messages by intent. Events in past tense (
OrderPlaced), commands imperative (ProcessPayment). AvoidOrderUpdated,DoSomething.
Wiring order in Program.cs
// 1. Core + handlers + outbox
services
.AddOpinionatedEventing()
.AddHandlersFromAssemblies(Assembly.GetExecutingAssembly())
.AddOutbox();
// 2. EF Core: interceptor on the DbContext, then the store
services.AddDbContext<AppDbContext>((sp, options) =>
{
options.UseSqlServer(connectionString);
options.AddInterceptors(sp.GetRequiredService<DomainEventInterceptor>());
});
services.AddOpinionatedEventingEntityFramework<AppDbContext>();
// 3. Sagas (only if used)
services.AddOpinionatedEventingSagas();
services.AddSaga<OrderSaga>();
// 4. Exactly one transport
services.AddRabbitMQTransport(o => { o.ConnectionString = "..."; o.ServiceName = "order-service"; });
// or: services.AddAzureServiceBusTransport(o => { ... });
In OnModelCreating call modelBuilder.ApplyOutboxConfiguration(Database.ProviderName) (and ApplySagaStateConfiguration(...) when using sagas), then add an EF migration.
Do / Don't
| Don't | Do |
|---|---|
| Publish to the broker directly | await publisher.PublishEventAsync(evt, ct) then SaveChangesAsync |
| Write two handlers for one command | One ICommandHandler<T>; use an event if several parties must react |
Send a "command" with PublishEventAsync | SendCommandAsync for commands |
| Assume exactly-once delivery | Make handlers idempotent (natural, unique constraint, or message ID key) |
Inject IPublisher into an aggregate | RaiseDomainEvent(...) |
Call SaveChanges in a domain method | Let the application layer save once |
Mix ApplyOutboxConfiguration() with CreateOutboxTable() | Pick one migration approach per project |
Use DateTime.UtcNow in saga timeouts | Inject TimeProvider; use FakeTimeProvider in tests |
| Register a saga handler by hand | AddSaga<T>() / AddSagaParticipant<T>() |
| Stand up real brokers in unit tests | Use OpinionatedEventing.Testing fakes |
When unsure
Check the API cheat sheet first. If an API you want is not on it, do not invent one. Look in the matching docs page, or tell the user the API is not documented.