Skip to main content

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​

  1. There is no direct publish path. IPublisher writes 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.
  2. Commands and events are different things.
    • ICommand: "please do X". Exactly one ICommandHandler<T> per command type. A second registration throws InvalidOperationException at startup.
    • IEvent: "X happened". Zero or more IEventHandler<T>.
  3. Send commands with SendCommandAsync, publish events with PublishEventAsync. Both live on IPublisher.
  4. Delivery is at-least-once. Handlers must tolerate duplicates. See Idempotency.
  5. Aggregates raise events, they do not publish. Extend AggregateRoot and call RaiseDomainEvent(...). The DomainEventInterceptor writes the outbox rows during SaveChangesAsync. Never inject IPublisher into an aggregate.
  6. One SaveChangesAsync commits business data and outbox rows together. Do not call it inside aggregate methods.
  7. Handler classes are registered by scanning. Use AddHandlersFromAssemblies. Do not register ICommandHandler<T> / IEventHandler<T> by hand.
  8. Sagas are registered explicitly. AddSaga<T>() for orchestrators, AddSagaParticipant<T>() for choreography participants. Both register the underlying event subscriptions for you.
  9. Transport is a DI choice. Handler, aggregate and saga code never changes between Azure Service Bus and RabbitMQ.
  10. Name messages by intent. Events in past tense (OrderPlaced), commands imperative (ProcessPayment). Avoid OrderUpdated, 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'tDo
Publish to the broker directlyawait publisher.PublishEventAsync(evt, ct) then SaveChangesAsync
Write two handlers for one commandOne ICommandHandler<T>; use an event if several parties must react
Send a "command" with PublishEventAsyncSendCommandAsync for commands
Assume exactly-once deliveryMake handlers idempotent (natural, unique constraint, or message ID key)
Inject IPublisher into an aggregateRaiseDomainEvent(...)
Call SaveChanges in a domain methodLet the application layer save once
Mix ApplyOutboxConfiguration() with CreateOutboxTable()Pick one migration approach per project
Use DateTime.UtcNow in saga timeoutsInject TimeProvider; use FakeTimeProvider in tests
Register a saga handler by handAddSaga<T>() / AddSagaParticipant<T>()
Stand up real brokers in unit testsUse 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.