Franz.Common.Mediator.SourceGenerator 3.0.0

Franz.Common.Mediator.SourceGenerator

Incremental Roslyn generator for compile-time Mediator handler registration, typed dispatch invokers, messaging manifests, and dispatch-call diagnostics.

Overview

The generator runs in each application compilation that references Franz.Common.Mediator. It discovers supported handler contracts in that compilation and emits an assembly-scoped registration contribution. It is included in the Mediator package analyzer assets; applications should normally reference Franz.Common.Mediator, not this generator package directly.

Installation

dotnet add package Franz.Common.Mediator.SourceGenerator

Most applications should reference Franz.Common.Mediator, which already includes the generator as an analyzer asset. Install this package directly only when the analyzer itself is the intended dependency.

Compatibility

• Targets .NET Standard 2.0.
• Uses Microsoft.CodeAnalysis 5.6.
• Package version follows the Franz.Common release version defined in common.targets.

Generated registration

The generator discovers implementations of:

• ICommandHandler<TCommand, TResult>
• ICommandHandler<TCommand>
• IQueryHandler<TQuery, TResult>
• INotificationHandler<TNotification>
• IEventHandler<TEvent>
• IStreamQueryHandler<TQuery, TResult>
• Supported IValidator<TRequest> contracts

It emits a module-initialized contribution for the containing assembly. The contribution registers handlers with DI, emits typed command/query/void-command invokers and event publisher invokers, and creates typed pre/post-processor invokers for discovered request contracts. Stream-query and notification handlers are registered for direct DI resolution.

The generator also emits a closed-generic default-pipeline contribution for supported request and notification contracts. AddFranzMediatorDefault<TAssemblyMarker>() applies that contribution. The generated pipeline contribution is distinct from the open-generic pipeline registrations used by the V2 default and standard bootstrap helpers.

Messaging manifest

When the messaging manifest contracts are present in the compilation, the generator emits an assembly contribution to MessagingManifestRegistry. The manifest records integration-event types and their discovered handler/subscription relationships. Event-based Kafka registration consumes this generated manifest to validate topic subscriptions; the generator does not create broker topics itself.

Diagnostic FRZMED001

The generator emits warning FRZMED001 when a statically typed call through IDispatcher.SendAsync, PublishNotificationAsync, or PublishEventAsync uses a concrete request/event type for which the current compilation contains no matching generated handler registration.

The diagnostic intentionally skips calls whose request type is an interface, abstract type, or generic type parameter because the concrete runtime type cannot be established reliably at compile time. The diagnostic is scoped to the current compilation; it cannot see handler registrations generated by a different assembly.

This is a compile-time warning, not a universal runtime fail-fast guarantee. Missing command, void-command, and query invokers are rejected by the generated invoker registry. Notification and generic event dispatch resolve handler collections through DI and may complete without invoking a handler when no matching registration exists. Keep integration tests for cross-assembly composition and message contracts.

Registration boundary

Use the Mediator registration API with the assembly that contains the handlers:

• AddFranzMediator(assemblies) for the V1 generated registration provider.
• AddFranzMediatorV2(handlerAssembly: ...) for the V2 generated registration provider.
• AddFranzMediatorDefault<TAssemblyMarker>() when applying generated closed-generic default pipelines.

The generator contributes registrations for the assembly being compiled. Selecting another assembly does not cause the generator to inspect that assembly at runtime.

License

MIT. See the repository LICENSE.