AstraFlow README

README проекта с github.com/seifmoustafa/AstraFlow. Одним файлом markdown: README.md.

AstraFlow

AstraFlow — Engineered Clarity

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.Assertions package, 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. All 1.x packages are deprecated — use the 2.x line.


Packages (16)

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 AstraFlow

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.Assertions ships as a standalone package starting in 2.4.0. Add it to test projects that need general-purpose assertions; it is not included by the AstraFlow convenience package.


Dispatch a request

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.


Mapping, projections, and source generation

See the Mapper Guide, Projection Guide, Convention Mapping Guide, Generators Guide, and Analyzers Guide.


Testing and assertions

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:

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.


Upgrading and 1.x deprecation policy

See the Version and Upgrade Guide, Migration Cookbook, and Changelog.


Target frameworks

Check Compatibility before installing integration packages into multi-targeted libraries.


Documentation map

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

Build, test, and pack from source

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.

AstraFlow (seifmoustafa/AstraFlow)

Ищем в базе…

Что это такое?AstraFlow — это модульный набор из 16 узкоспециализированных пакетов для .NET. Они отвечают за явную диспетчеризацию запросов, маппинг объектов, проекции запросов, анализаторы на этапе компиляции, генераторы исходного кода, диагностику, наблюдаемость и сценарии тестирования.
Это фреймворк или библиотека?Это набор библиотек NuGet, а не один фреймворк. Вы устанавливаете только те пакеты, которые нужны вашему приложению, а необязательные интеграции держите изолированными.
Для каких версий .NET это сделано?Базовые пакеты рассчитаны на netstandard2.0 и на версии от net8.0 до net10.0. Интеграции с ASP.NET Core и EF Core требуют net10.0, а CLI — это инструмент .NET для net10.0.
Можно ли ещё пользоваться линейкой 1.x?Нет. Все пакеты 1.x помечены на NuGet.org как устаревшие, поэтому и новым, и уже существующим проектам стоит использовать линейку 2.x. Перед тем как зафиксировать версию, проверьте на NuGet.org последнюю версию 2.x.
Что на самом деле создаёт генератор на этапе компиляции?Методы с атрибутом [AstraGenerateMapping], которые нужно включать явно, создают типизированные маппинги на этапе компиляции. Версия 2.4.0 расширяет это на унаследованные публичные свойства, скалярные типы Guid и временные типы, позиционные record, DTO с основным конструктором и инициализаторы init-only.
Что умеет CLI AstraFlow?Инструмент .NET AstraFlow.Cli проверяет и валидирует регистрации, формирует по ним отчёты и сравнивает их, а также экспортирует графы в формате Mermaid или Canvas. Кроме того, он запускает сканирование только для чтения при миграции утверждений (assertions).
Что нового в линейке 2.4.x?Линейка 2.4.x добавляет отдельный пакет AstraFlow.Assertions, расширенную генерацию маппингов на этапе компиляции и анализ миграции утверждений в CLI только для чтения.
Автор
seifmoustafa
Размер
42.8 MB
Звёзды
664
Возраст
6 мес
Коммиты · 90 дней