RequestFlow.Abstractions 1.0.0-preview.9

equestFlow

This is a request/handler mediator for .NET. Built-in validation checks mediator and application-defined rules at startup. Frozen maps route requests through prebuilt execution plans.

Supports Task and ValueTask requests, stages, streams, and events. Additionally, RequestFlow.Cqrs adds a type-enforced command/query split. Registration runs at startup without a source generator, analyzer, or other build step.

Status: preview on NuGet. Install with the --prerelease flag:

dotnet add package RequestFlow --prerelease

See the preview.9 release notes for additions and API renames.

Getting started: define a request, register its handler, and send it.

Startup validation

AddRequestFlow collects registrations. ValidateRequestFlow() closes the stage chains and runs every built-in and application-defined rule. If all validations pass, it freezes the valid model. Otherwise, it reports all problems in a single RequestFlowValidationException.

builder.Services
    .AddRequestFlow(options =>
    {
        options.RegisterHandlersFromCallingAssembly();
        options.AddStage(
            typeof(ValidationStage<,>),
            stage => stage.WhereHandlerImplements<IOrdersCommandHandler>());
    })
    .AddValidationRule<CommandValidationStageRule>();

WebApplication app = builder.Build();
app.Services.ValidateRequestFlow();

In the modular sample, CommandValidationStageRule reads the frozen stage chain and rejects commands without ValidationStage<,>. The convention is checked at startup instead of during code review.

A custom rule can inspect request and response contracts, selected handlers, closed stages, stream shapes, events, and event strategies. It reports into the same exception as the built-in checks. See Validation rules.

Why RequestFlow

• Startup validation reports missing and duplicate handlers, invalid stage closures, event problems, CQRS conflicts, and application-defined rule failures in one exception.
• Task request, ValueTask request, stream, and event plans freeze once. Dispatch starts with a map lookup and uses no reflection, LINQ, or locking.
• Repeated AddRequestFlow calls are additive, so each module can register its assembly into the same application model.
• Task requests, ValueTask requests, streams, and events use separate dispatch surfaces. The optional CQRS package adds Task and ValueTask command/query dispatchers plus stream-query dispatch.

Modular monoliths

The sample keeps module registration beside module code:

builder.Services.AddOrdersModule().AddCqrs();
builder.Services.AddAuditModule();

AddOrdersModule() and AddAuditModule() each call AddRequestFlow for their own assembly and add to the same registry. An OrderPlaced event from Orders can reach an Audit handler, and startup validation covers both modules.

See the sample walkthrough.

Modern .NET first

RequestFlow targets .NET 10 and .NET 8 directly. It also ships netstandard2.0 and net462 assets for applications that still run on older targets.

Runtime registration uses assembly discovery and dynamic generic construction during freeze, so RequestFlow does not support trimming or NativeAOT. See Compatibility.

Coming from MediatR

Most request and handler changes are mechanical. Event semantics and some extension points differ.

Void handlers return plain Task; Unit does not appear in user code. Existing Task and Task<T> handlers keep those return types.

The MediatR migration guide covers the file-by-file sequence, event differences, conditional registration, and unsupported extension points.

Packages

• RequestFlow.Abstractions holds Task and ValueTask requests, handlers, dispatchers, stages, streaming, events, publish strategies, validation models, and exceptions. It has no package dependency on net8.0 or net10.0.
• RequestFlow adds Task and ValueTask dispatch, event publication, assembly and manual registration, startup validation, and frozen execution plans.
• RequestFlow.Cqrs.Abstractions holds Task and ValueTask command/query contracts, stream-query contracts, handlers, and typed dispatchers.
• RequestFlow.Cqrs adds the Task and ValueTask command/query dispatchers, stream-query dispatcher, and AddCqrs() validation rule on top of the core runtime.

Install a runtime package at the composition root. Reference an abstractions package directly from a domain or application layer that should not depend on runtime registration.

Documentation

• Getting started: install, first request and handler, dispatching
• ValueTask requests: measured opt-in requests, stages, CQRS, and consumption rules
• Registration: scanning, manual registration, generic handlers, additive calls, startup validation
• Stages: wrapping handlers, execution order, filters, and request selection
• Pipeline inspection: declared handlers, ordered stages, and stage exclusion reasons
• Streaming: stream requests, stream stages, cancellation, and enumeration timing
• Events: polymorphic delivery, strategies, ordering, failures, and cancellation
• Validation rules: application-defined checks over the frozen registration model
• Compatibility: modern targets, downlevel targets, trimming, and NativeAOT
• Migrating from MediatR: concept mapping and semantic differences
• Service lifetimes: handler, stage, dispatcher, and publisher lifetimes
• Exceptions: exceptions, timing, and fixes
• Modular sample: an API host with independently registered Orders and Audit modules

Contributing

Design feedback is the most useful contribution while the packages are in preview.

License

MIT. See LICENSE.