项目的 README,来自 github.com/seifmoustafa/AstraFlow。合并为一个 markdown 文件:README.md。

A modular .NET suite of 16 focused packages for explicit request dispatch, object mapping, query projections, compile-time analyzers, source generators, diagnostics, observability, and test workflows. Install only the packages your application needs and keep optional integrations isolated.
Getting Started · Package Selection · Version & Upgrade Guide · Compatibility · Changelog · Branding
Release status & support policy: The 2.4.x line includes the standalone
AstraFlow.Assertionspackage, expanded compile-time mapping generation, and read-only CLI assertion migration analysis. The 2.4.1 patch fixed the package README image on NuGet.org; 2.4.2 through 2.4.4 add compile-tested assertion migration compatibility, with 2.4.4 extending formatted failure reasons and case-insensitive string containment checks. Check NuGet.org for the latest package version before pinning it. All1.xpackages are deprecated — use the2.xline.
| Category | Package | Targets | Role |
|---|---|---|---|
| Core | AstraFlow |
netstandard2.0, net8.0, net9.0, net10.0 |
Convenience umbrella for AstraFlow.Contracts, AstraFlow.Mediator, and AstraFlow.Mapper |
| Core | AstraFlow.Contracts |
netstandard2.0, net8.0, net9.0, net10.0 |
Lightweight mediator abstractions (IRequest, INotification, streams, pipelines) with zero runtime dependencies |
| Core | AstraFlow.Mediator |
netstandard2.0, net8.0, net9.0, net10.0 |
Request/command/stream dispatch, notifications, pipeline behaviors, processors, scanning, and handler coverage validation |
| Core | AstraFlow.Mapper |
netstandard2.0, net8.0, net9.0, net10.0 |
Explicit object mapping catalogs, startup validation, named projections, and secure ID abstractions |
| Core | AstraFlow.Mapper.Conventions |
netstandard2.0, net8.0, net9.0, net10.0 |
Opt-in convention mapping with deterministic plans, strict validation, and sensitive-field safeguards |
| Core | AstraFlow.Security |
netstandard2.0, net8.0, net9.0, net10.0 |
Shared sensitive-name classification and redaction policy primitives |
| Core | AstraFlow.Diagnostics |
netstandard2.0, net8.0, net9.0, net10.0 |
Framework-neutral JSON and Markdown registration and validation reports |
| Tooling | AstraFlow.Analyzers |
netstandard2.0 (analyzer) |
Build-time Roslyn diagnostics for mediator, mapper, and projection contracts |
| Tooling | AstraFlow.Generators |
netstandard2.0 (generator) |
Compile-time mediator/mapper metadata plus opt-in typed mapping generation ([AstraGenerateMapping]) |
| Tooling | AstraFlow.Cli |
net10.0 (.NET tool) |
CLI inspect, validate, report, diff, Mermaid/Canvas graphs, and read-only assertion migration scan (expanded in 2.4.0) |
| Integrations | AstraFlow.AspNetCore |
net10.0 |
Minimal APIs, controllers, problem details, diagnostics endpoints, and health summaries |
| Integrations | AstraFlow.FluentValidation |
net8.0, net9.0, net10.0 |
Validation pipeline behaviors (fail-fast and aggregate errors), localization hooks, and diagnostics |
| Integrations | AstraFlow.OpenTelemetry |
net8.0, net9.0, net10.0 |
Production-safe ActivitySource tracing and Meter metrics with default redaction |
| Integrations | AstraFlow.Mapper.EntityFrameworkCore |
net10.0 |
Optional EF Core queryable projection translation validation |
| Testing | AstraFlow.Testing |
netstandard2.0, net8.0, net9.0, net10.0 |
Framework-neutral test fakes, recording harnesses, and flow test helpers |
| Testing | AstraFlow.Assertions |
netstandard2.0, net8.0, net9.0, net10.0 |
Standalone, runner-neutral general-purpose assertions with zero production package dependencies |
See the Package Selection Guide for boundary rules and dependency isolation guarantees (AstraFlow.Mapper never pulls EF Core; AstraFlow.Mediator never pulls FluentValidation or OpenTelemetry).
Install the umbrella convenience package when a project uses both mediator and explicit mapping:
dotnet add package AstraFlow
For cleaner layer boundaries, reference only what each assembly needs:
# Shared domain/API contracts library (no runtime dependency)
dotnet add package AstraFlow.Contracts
# Application layer packages
dotnet add package AstraFlow.Mediator
dotnet add package AstraFlow.Mapper
AstraFlow.Assertionsships as a standalone package starting in2.4.0. Add it to test projects that need general-purpose assertions; it is not included by theAstraFlowconvenience package.
Register the assembly containing your handlers, resolve ISender, and dispatch typed requests with explicit cancellation flow:
using System;
using System.Threading;
using System.Threading.Tasks;
using AstraFlow;
using AstraFlow.Mediator;
using Microsoft.Extensions.DependencyInjection;
var services = new ServiceCollection();
services.AddAstraFlow(assemblyMarkerTypes: typeof(CreateOrderHandler));
await using var serviceProvider = services.BuildServiceProvider();
var sender = serviceProvider.GetRequiredService<ISender>();
using var cancellationTokenSource = new CancellationTokenSource();
OrderCreated result = await sender.Send(
new CreateOrder("ORD-1042"),
cancellationTokenSource.Token);
public sealed record CreateOrder(string Number) : IRequest<OrderCreated>;
public sealed record OrderCreated(Guid Id, string Number);
public sealed class CreateOrderHandler : IRequestHandler<CreateOrder, OrderCreated>
{
public Task<OrderCreated> Handle(
CreateOrder request,
CancellationToken cancellationToken)
{
return Task.FromResult(new OrderCreated(Guid.NewGuid(), request.Number));
}
}
Use ISender, IPublisher, or IStreamSender when a consumer needs only one slice of the mediator contract. Missing or duplicate request handlers fail explicitly during startup validation.
See Getting Started, the Mediator Guide, and Mediator Scenarios.
AstraFlow.Mapper): Declared mapping catalogs, deterministic startup validation, named query projections, and secure ID encoding abstractions.AstraFlow.Mapper.Conventions): Never active by default; generates inspectable mapping plans with sensitive-member write safeguards backed by AstraFlow.Security.AstraFlow.Mapper.EntityFrameworkCore): Validates queryable projections against the configured EF Core provider.AstraFlow.Generators): Opt-in [AstraGenerateMapping] methods supporting typed scalar, collection, [AstraValueConverter], and [AstraDerivedMapping] shapes in 2.3.0. Version 2.4.0 expands generation to inherited public source properties, Guid/temporal scalars, safe nullable scalar flows (T -> T?, T? -> T?), positional records, primary-constructor DTOs, and public init-only initializers.See the Mapper Guide, Projection Guide, Convention Mapping Guide, Generators Guide, and Analyzers Guide.
AstraFlow.Testing ships test fakes and harnesses for mediator pipelines, mapping catalogs, projections, diagnostics, and secure ID codecs on 2.3.0.
AstraFlow.Assertions (targeting 2.4.0) adds a zero-dependency, test-runner-neutral assertion package covering:
DateTime/DateTimeOffset/TimeSpan/DateOnly/TimeOnly comparisons.StringComparison checks, */? wildcards, timeout-bounded regex, WithInnerException chaining, sync/async ArgumentException parameter-name checks, deferred Invoking/Awaiting/Enumerating helpers, finite-timeout async delegate and TaskCompletionSource completion/non-completion checks, one-run sync/async and subject-method execution-time measurement, and explicit AssertionScope multi-failure aggregation.IAsyncEnumerable<T> & dictionaries: Single-pass enumeration, indexed-item and immediate-neighbor checks, ordered prefix/suffix checks, positive and negative ordered/consecutive matching for synchronous and asynchronous sequences, key-selected ascending/descending order, structural-equivalency membership/all-item checks, uniqueness and multiset checks, exact and assignable item-type checks with typed chaining, async stream assertions on net8.0/net9.0/net10.0, and comparer-aware dictionary entry checks, including negative pair and predicate checks.IncludingFields()), ordered or order-independent collections, path-based member selection, per-call exclusions, custom comparers, and recursion limits.XDocument/XElement structural equivalence, non-consuming XmlReader cursor checks, HttpResponseMessage status/header assertions plus buffered async text body checks, and stream mode and position/length assertions; buffered-size checks are available on net8.0 and later without reading or disposing streams.INotifyPropertyChanged notifications, inspect captured sender/arguments, and automatically unsubscribe when the monitor is disposed.using AstraFlow.Assertions; // Available in 2.4.0
response.StatusCode.Should().Be(201);
items.Should().ContainSingle(item => item.Id == expectedId);
Func<Task> save = () => service.SaveAsync();
await save.Should().NotThrowAsync();
See the Testing Guide and Assertions Guide for full signatures, target matrix, and caveats.
1.x deprecation policy1.x releases are deprecated on NuGet.org. New projects and existing consumers should use the 2.x line. Check NuGet.org for availability of the exact package version before upgrading.2.x preserves existing package boundaries and mediator/mapper entry points: update the AstraFlow package versions in your .csproj or Directory.Packages.props, restore, build, and run tests.AstraFlow.Assertions or 2.4.0 generated mapping expansions is optional per test project or mapping declaration.See the Version and Upgrade Guide, Migration Cookbook, and Changelog.
netstandard2.0, net8.0, net9.0, net10.0net8.0, net9.0, net10.0net10.0netstandard2.0 compiler assets (analyzers/dotnet/cs, no runtime lib/ dependency)net10.0 .NET toolCheck Compatibility before installing integration packages into multi-targeted libraries.
| Topic | Guides |
|---|---|
| Onboarding & Packages | Getting Started · Package Selection · Architecture · API Reference · Compatibility |
| Mediator & Integrations | Mediator · Mediator Scenarios · ASP.NET Core · FluentValidation · OpenTelemetry |
| Mapper, Generators & CLI | Mapper · Mapper Scenarios · Projections · Projection Scenarios · Conventions · EF Core · Generators · Analyzers · CLI |
| Diagnostics, Security & Tests | Diagnostics · Endpoint Safety · Security · Testing · Assertions (2.4.0) · Benchmarks |
| Upgrades & Troubleshooting | Version & Upgrade Guide · Migration Cookbook · Troubleshooting · Branding |
| Roadmap & Governance | Roadmap · Decision Log · API Governance · Security & Supply Chain · Security Policy · Contributing · Support · MIT License |
dotnet build AstraFlow.slnx --configuration Release
dotnet test AstraFlow.slnx --configuration Release --no-build
.\scripts\pack.ps1
For release verification, SourceLink, reproducibility, and NuGet publishing rules, see the Release Checklist, Publishing Guide, and Community Release Guide. Note that NuGet package READMEs require absolute raw GitHub URLs matching the target release tag/branch before packing for NuGet.org.