Genocs.Messaging Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.Messaging Agent Reference

Purpose

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

  • What Genocs.Messaging 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
Project filesrc/Genocs.Messaging/Genocs.Messaging.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleBroker-agnostic messaging abstractions for publish/subscribe and CQRS dispatcher bridge wiring
Core themesIBusPublisher and IBusSubscriber contracts, message metadata accessors, AsyncLocal context propagation, CQRS integration helpers, routing metadata attribute

Use This Package When

  • Defining broker-agnostic publish and subscribe contracts in application code.
  • Bridging CQRS ICommandDispatcher and IEventDispatcher to a bus publisher.
  • Registering command and event subscriber handlers via scoped DI resolution.
  • Passing correlation context and message metadata across async execution flow.
  • Annotating message types with exchange, routing key, queue, and external flags.

Do Not Assume

  • This package does not provide a broker implementation; transport packages implement interfaces.
  • Subscriber helper methods create a new DI scope per delivered message.
  • Correlation and message properties accessors are AsyncLocal-based and flow with async context.

High-Value Entry Points

Broker abstraction contracts

Message metadata contracts

Correlation context access

CQRS bus helper methods

CQRS dispatcher registration

CQRS dispatcher implementation

Decision Matrix For Agents

GoalPreferred APINotes
Publish any message through transportIBusPublisher.PublishAsyncCore abstraction; transport package handles wire protocol
Publish command with message contextIBusPublisher.SendAsync extensionCQRS helper delegates to PublishAsync with messageContext
Publish event with message contextIBusPublisher.PublishAsync extensionCQRS helper for IEvent messages
Subscribe command and resolve handlerIBusSubscriber.SubscribeCommandCreates scope and resolves ICommandHandler per message
Subscribe event and resolve handlerIBusSubscriber.SubscribeEventCreates scope and resolves IEventHandler per message
Bridge command dispatcher to busAddServiceBusCommandDispatcherRegisters ICommandDispatcher -> ServiceBusMessageDispatcher
Bridge event dispatcher to busAddServiceBusEventDispatcherRegisters IEventDispatcher -> ServiceBusMessageDispatcher
Access ambient correlation contextICorrelationContextAccessorAsyncLocal-backed value consumed by dispatcher bridge

Minimal Integration Recipe

Install 

dotnet add package Genocs.Messaging

Setup in Program.cs 

using Genocs.Core.Builders;
using Genocs.Messaging;
using Genocs.Messaging.CQRS;

var builder = WebApplication.CreateBuilder(args);

IGenocsBuilder gnxBuilder = builder.AddGenocs();

gnxBuilder
    .AddServiceBusCommandDispatcher()
    .AddServiceBusEventDispatcher();

builder.Services.AddSingleton<ICorrelationContextAccessor, CorrelationContextAccessor>();
builder.Services.AddSingleton<IMessagePropertiesAccessor, MessagePropertiesAccessor>();

gnxBuilder.Build();

var app = builder.Build();

app.Run();

Behavior Notes That Affect Agent Decisions

  • IBusPublisher is the single publishing abstraction; CQRS SendAsync and PublishAsync helpers are thin wrappers.
  • SubscribeCommand and SubscribeEvent create IServiceScope for each message, ensuring handler dependencies are resolved per-message.
  • ServiceBusMessageDispatcher reads ICorrelationContextAccessor.CorrelationContext and forwards it as messageContext.
  • AddServiceBusCommandDispatcher and AddServiceBusEventDispatcher register ServiceBusMessageDispatcher as transient.
  • MessagePropertiesAccessor and CorrelationContextAccessor both use AsyncLocal holder classes for ambient context flow.
  • Setting accessor values clears previously held context in the same AsyncLocal slot before assigning a new one.
  • MessageAttribute carries routing metadata fields but does not enforce broker behavior by itself.

Source-Accurate Capability Map

Publish and subscribe abstractions

  • Defines a generic publish contract with optional IDs, headers, span context, and message context.
  • Defines a generic subscribe contract receiving service provider, message payload, and message context.
  • Exposes routing metadata container attribute for message classes.

Files:

Message metadata model

  • Defines immutable metadata contract for MessageId, CorrelationId, Timestamp, and headers.
  • Provides mutable concrete metadata model.
  • Provides accessor interface for ambient metadata retrieval.
  • Provides AsyncLocal-backed accessor implementation.

Files:

Correlation context propagation

  • Defines ambient correlation context accessor contract.
  • Stores correlation context in AsyncLocal to flow through async calls.
  • Supports clearing and replacing context safely.

Files:

CQRS publish helper extensions

  • Provides command send extension targeting ICommand.
  • Provides event publish extension targeting IEvent.
  • Normalizes messageContext forwarding to underlying IBusPublisher.

Files:

CQRS subscriber helper extensions

  • Subscribes command type and resolves ICommandHandler from scoped provider.
  • Subscribes event type and resolves IEventHandler from scoped provider.
  • Encapsulates handler invocation wiring and disposal scope.

Files:

CQRS dispatcher bridge to bus

  • Registers command and event dispatchers mapped to ServiceBusMessageDispatcher.
  • Implements ICommandDispatcher and IEventDispatcher on one class.
  • Forwards CQRS operations to IBusPublisher with ambient correlation context.

Files:

Dependencies

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

  • Genocs.Core
Last modified on March 21, 2026
Edit this page on GitHub
← Genocs.Logging Agent Reference
Genocs.Messaging.Outbox Agent Reference →