Genocs.Messaging.RabbitMQ Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.Messaging.RabbitMQ Agent Reference

Purpose

This document is optimized for AI-assisted development sessions. It prioritizes fast retrieval of:

  • What Genocs.Messaging.RabbitMQ is responsible for
  • Which APIs to call for specific goals
  • Where source of truth lives
  • What constraints and runtime behaviors matter

Quick Facts

KeyValue
PackageGenocs.Messaging.RabbitMQ
Project filesrc/Genocs.Messaging.RabbitMQ/Genocs.Messaging.RabbitMQ.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleRabbitMQ transport implementation for Genocs messaging abstractions with conventions, retries, DLQ flow, plugins, and tracing headers
Core themesAddRabbitMQAsync registration, IBusPublisher and IBusSubscriber implementations, conventions builder/provider, background consumer service, plugin chain, serializer abstraction

Use This Package When

  • Binding Genocs.Messaging abstractions to RabbitMQ transport.
  • Publishing messages with conventions-driven exchange, routing key, and queue naming.
  • Running background consumer handling with retry and optional dead-letter routing.
  • Propagating correlation context and tracing headers over RabbitMQ.
  • Extending message handling with plugin middleware and custom exception mappers.

Do Not Assume

  • AddRabbitMQAsync is asynchronous and must be awaited.
  • Host names are required; registration throws when rabbitmq host list is empty.
  • UseRabbitMQ returns a subscriber facade and does not auto-subscribe handlers unless Subscribe calls are made.
  • Producer channels are created per managed thread and bounded by max producer channels.
  • Retries in background consumer do not imply automatic success; failure mapping and dead-letter settings alter final ack/nack behavior.

High-Value Entry Points

Registration and host integration

Publish and subscribe abstractions

Client, serialization, and context

Conventions and routing metadata

Plugin and failure extension points

Exchange initialization and processing constraints

Decision Matrix For Agents

GoalPreferred APINotes
Register RabbitMQ transportAddRabbitMQAsyncWires connections, publisher, subscriber, background service, conventions
Add typed subscriptions in pipelineUseRabbitMQ then SubscribePushes subscriber actions to internal channel consumed by hosted service
Publish broker messageIBusPublisher.PublishAsyncUses RabbitMQPublisher then RabbitMQClient.SendAsync
Customize message routing namesIConventionsBuilder and optionsSupports MessageAttribute values plus casing and queue template
Add pre-handler middlewareplugins argument on AddRabbitMQAsync with IRabbitMqPluginsRegistry.AddBuilds linked plugin chain around core handler
Map exceptions to failure eventsAddExceptionToFailedMessageMapper or AddExceptionToMessageMapperControls retry, failed publish, and dead-letter path
Switch serializer implementationpass serializer argument to AddRabbitMQAsync or register custom IRabbitMQSerializerDefaults to System.Text.Json serializer
Tune retry and dead-letter behaviorRabbitMQOptions.Retries, RetryInterval, DeadLetter, RequeueFailedMessagesBackground service decides ack/nack and DLX behavior

Minimal Integration Recipe

Install 

dotnet add package Genocs.Messaging.RabbitMQ

Setup in Program.cs 

using Genocs.Core.Builders;
using Genocs.Messaging.RabbitMQ;

var builder = WebApplication.CreateBuilder(args);

IGenocsBuilder gnxBuilder = builder.AddGenocs();

await gnxBuilder.AddRabbitMQAsync();

gnxBuilder.Build();

var app = builder.Build();

app.UseRabbitMQ();

app.Run();

Behavior Notes That Affect Agent Decisions

  • AddRabbitMQAsync uses registry key messageBrokers.rabbitmq and skips duplicate registrations.
  • AddRabbitMQAsync creates two RabbitMQ connections, one consumer and one producer.
  • Producer publish path injects traceparent and tracestate headers when activity data is available.
  • Consumer path supports retry policy with wait-and-retry based on configured retries and interval.
  • When message processing timeout is configured, timed-out handlers trigger RabbitMqMessageProcessingTimeoutException.
  • FailedMessage mapping controls whether to retry, acknowledge, or move message to dead-letter flow.

Source-Accurate Capability Map

Transport registration and DI wiring

  • Registers core messaging services, conventions services, and context accessors.
  • Registers background consumer hosted service and exchange initializer.
  • Supports plugin registry and plugin executor registration.
  • Supports SSL and optional custom connection factory configuration.

Files:

Publish pipeline

  • Resolves routing conventions by message type.
  • Serializes payload and builds RabbitMQ basic properties.
  • Adds correlation, message ID, timestamp, optional context, and tracing headers.
  • Publishes using producer channel pool keyed by managed thread id.

Files:

Subscribe and consume runtime

  • Queues subscribe actions through MessageSubscribersChannel.
  • Declares and binds queues with optional dead-letter setup.
  • Processes incoming messages with scoped services and correlation/message properties accessors.
  • Acknowledges, retries, nacks, and dead-letter transitions based on processing outcome.

Files:

Conventions and routing computation

  • Computes routing key, exchange, and queue from options plus MessageAttribute metadata.
  • Supports snake_case naming mode and queue template token replacement.
  • Caches resolved conventions and allows explicit overrides in registry.

Files:

Plugin chain and failure mapping

  • Supports chain-of-responsibility plugin execution around handler invocation.
  • Allows custom exception-to-message mapping for legacy behavior.
  • Supports richer failure mapping with retry and dead-letter intent flags.

Files:

Serializer and options surface

  • Defines serializer contract for generic and typed deserialization.
  • Provides System.Text.Json default serializer.
  • Provides Newtonsoft.Json serializer alternative.
  • Exposes extensive RabbitMQ option model for connection, queue, exchange, DLQ, QoS, context, and logging.

Files:

Dependencies

From src/Genocs.Messaging.RabbitMQ/Genocs.Messaging.RabbitMQ.csproj:

  • Genocs.Messaging
  • RabbitMQ.Client
  • Polly
  • Newtonsoft.Json
Last modified on March 21, 2026
Edit this page on GitHub
← Genocs.Messaging.Outbox.MongoDB Agent Reference
Genocs.Persistence.MongoDB Agent Reference →