AstraFlow.Testing 1.6.2

AstraFlow

AstraFlow is a MIT-licensed .NET package family for explicit CQRS dispatch and source-auditable object mapping.

It was built to keep production applications free from runtime license checks, hidden mapping behavior, and framework lock-in. The v1 design is deliberately small: secure defaults, clear errors, explicit extension points, and package-quality diagnostics before optional convention layers are added.

Release And Repository Links

NuGet shows package history under the Release Notes tab. GitHub shows only selected community files as repository tabs, so the README is the main public hub for everything else.

Packages

Documentation Map

Target Framework

Since 1.4.0, AstraFlow.Contracts, AstraFlow, AstraFlow.Mediator, AstraFlow.Mapper, AstraFlow.Diagnostics, and AstraFlow.Testing ship netstandard2.0, net8.0, net9.0, and net10.0 assets. Since 1.5.0, AstraFlow.Mapper.Conventions ships the same non-EF targets. AstraFlow.Mapper.EntityFrameworkCore remains net10.0 because it follows the EF Core 10 package line.

Public API At A Glance

Registration

Mediator

Mapper

Diagnostics

Testing

Entity Framework Core

Design Principles

• Explicit by default: mapping rules must be code you can review.
• Security first: sensitive fields are not mapped by naming convention unless a future optional package is explicitly enabled.
• Clear failure modes: missing handlers, duplicate handlers, missing mappings, duplicate mappings, and undeclared mappings fail with actionable messages.
• No application lock-in: AstraFlow does not depend on any private product, Result, ASP.NET Core MVC, FluentValidation, tenants, permissions, or a specific ID encryption implementation.
• Extension-ready: pipelines, notification failure policies, projections, and secure ID codecs are designed as narrow public contracts.

Quick Start: Mediator

using AstraFlow.Mediator;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddAstraFlowMediator(typeof(CreateInvoiceCommand));

using var provider = services.BuildServiceProvider();
var sender = provider.GetRequiredService<ISender>();

var id = await sender.Send(new CreateInvoiceCommand("INV-1001"));

public sealed record CreateInvoiceCommand(string Number) : IRequest<Guid>;

public sealed class CreateInvoiceCommandHandler
    : IRequestHandler<CreateInvoiceCommand, Guid>
{
    public Task<Guid> Handle(CreateInvoiceCommand request, CancellationToken cancellationToken)
    {
        return Task.FromResult(Guid.NewGuid());
    }
}

Quick Start: Pipeline Behavior

Pipeline behaviors run in registration order and may short-circuit by not calling next.

services.AddScoped(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
services.AddScoped(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
services.AddScoped(typeof(IPipelineBehavior<,>), typeof(FeatureGateBehavior<,>));

Quick Start: Mapper

using AstraFlow.Mapper;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddAstraFlowMapper(typeof(UserMappingRule));

using var provider = services.BuildServiceProvider();
var mapper = provider.GetRequiredService<IMapper>();

var dto = mapper.Map<UserResponse>(new User(Guid.NewGuid(), "admin"));

public sealed record User(Guid Id, string UserName);
public sealed record UserResponse(Guid Id, string UserName);

public sealed class UserMappingRule : IDeclaredObjectMappingRule
{
    public IReadOnlyCollection<ObjectMappingPair> DeclaredMappings { get; } =
    [
        ObjectMappingPair.Create<User, UserResponse>()
    ];

    public bool CanMap(Type sourceType, Type destinationType)
    {
        return sourceType == typeof(User) && destinationType == typeof(UserResponse);
    }

    public object? Map(object? source, Type destinationType, IMapper mapper)
    {
        var user = (User)source!;
        return new UserResponse(user.Id, user.UserName);
    }
}

Quick Start: Projections

Register projections with the mapper marker assembly, then resolve them through the registry:

public sealed class UserListProjection : INamedProjection<User, UserListItem>
{
    public string Name => "list";

    public Expression<Func<User, UserListItem>> Expression =>
        user => new UserListItem(user.Id, user.UserName);
}

services.AddAstraFlowMapper(
    [typeof(UserListProjection)],
    options =>
    {
        options.ValidateProjectionCatalogOnStartup = true;
        options.ProjectionValidationMode = ProjectionValidationMode.Warning;
    });

var registry = provider.GetRequiredService<IProjectionRegistry>();
var query = db.Users.ProjectWith<User, UserListItem>(registry, "list");

Projection validation reports warnings by default. Set ProjectionValidationMode.Error in CI or strict startup validation when projection findings should fail the build or application startup.

Quick Start: Convention Mapping

Install the optional conventions package only where convention mapping is deliberate:

dotnet add package AstraFlow.Mapper.Conventions --version 1.5.2

Register exact pairs through a profile:

services.AddAstraFlowMapper(typeof(UserProfile));
services.AddAstraFlowConventionMapping(catalog => catalog.AddProfile<UserProfile>());

public sealed class UserProfile : ConventionMappingProfile
{
    public UserProfile()
    {
        CreateMap<User, UserResponse>()
            .ForMember(destination => destination.DisplayName, member => member
                .MapFrom(source => source.Name)
                .Required())
            .ForMember(destination => destination.Score, member => member.NullSubstitute(0))
            .Ignore(nameof(UserResponse.InternalNote));
    }
}

Convention mapping stays disabled for every pair that is not registered. Member rules, converters, conditions, null substitution, enum decisions, and constructor-bound record members are included in mapping plans so every convention-created member can be reviewed before publishing.

Existing-destination updates are separate from read DTO mapping:

CreateMap<UserPatch, User>()
    .EnableUpdateMapping()
    .ForMember(destination => destination.Email, member => member.Condition(source => source.HasEmail));

provider.GetRequiredService<IConventionMapper>().MapInto(patch, user);

Sensitive destination writes remain blocked unless explicitly allowed.

Quick Start: EF Core Projection Checks

Install the optional package only in projects that need EF Core validation:

dotnet add package AstraFlow.Mapper.EntityFrameworkCore --version 1.5.2

Then ask EF Core to translate registered projections without executing the query:

using AstraFlow.Mapper.EntityFrameworkCore;

var efReport = dbContext.ValidateProjectionTranslations(registry);

Static projection validation catches high-risk expression patterns such as custom method calls. EF Core validation proves the source entity is mapped and the provider can generate SQL for the projection shape.

Secure ID Mapping

AstraFlow.Mapper provides the abstraction, not the cryptography. Applications own the encryption implementation.

services.AddScoped<ISecureIdCodec, MySecureIdCodec>();
services.AddScoped<SecureIdMapper>();

Mapping rules can then depend on SecureIdMapper and emit encrypted string IDs without coupling the package to application secrets.

Notification Failure Policies

Notifications are sequential by default. Configure how failures are handled:

services.Configure<NotificationPublishOptions>(options =>
{
    options.FailurePolicy = NotificationFailurePolicy.Aggregate;
    options.PublishStrategy = NotificationPublishStrategy.BoundedParallel;
    options.MaxDegreeOfParallelism = 4;
});

Policies:

• FailFast: stop at the first failing handler.
• Continue: log failures and run remaining handlers.
• Aggregate: run all handlers, then throw one AggregateException.

Publish strategies:

• Sequential: default and safest for ordered handlers or shared scoped state.
• Parallel: run all handlers concurrently.
• BoundedParallel: run handlers concurrently with a maximum degree of parallelism.

Quick Start: Diagnostics

Register diagnostics after mediator and mapper services:

using AstraFlow.Diagnostics;

services.AddAstraFlowMediator(typeof(CreateInvoiceCommand));
services.AddAstraFlowMapper(typeof(UserMappingRule));
services.AddAstraFlowDiagnostics(options =>
{
    options.AssemblyMarkerTypes.Add(typeof(CreateInvoiceCommand));
    options.AssemblyMarkerTypes.Add(typeof(UserMappingRule));
});

Create reports:

var reporter = provider.GetRequiredService<IAstraFlowDiagnosticsReporter>();

var report = reporter.CreateReport();
var json = reporter.CreateJsonReport();
var markdown = reporter.CreateMarkdownReport();

Diagnostics are framework-neutral and do not expose request payloads, DTO payloads, secrets, tokens, or connection strings.

Quick Start: Testing

Install the optional testing package in test projects:

dotnet add package AstraFlow.Testing --version 1.5.2

Use the fake mediator to record requests and notifications:

var mediator = new FakeMediator()
    .RespondWith<CreateInvoiceCommand, Guid>(Guid.NewGuid());

var id = await mediator.Send(new CreateInvoiceCommand("INV-1001"));

mediator.Requests.SingleSent<CreateInvoiceCommand>();

The testing package is framework-neutral and does not depend on xUnit, NUnit, MSTest, FluentAssertions, or a mocking framework.

v1 Non-Goals

AstraFlow v1 intentionally does not include convention mapping, flattening, reverse-map generation, compatibility shims, source generators, or analyzers. Those belong in optional packages after the explicit core is stable in real production use.

Roadmap

The long-term plan is to continue improving mediator ergonomics, optional convention mapping, advanced mapping parity, analyzers, source generators, OpenTelemetry hooks, benchmark projects, ASP.NET Core helpers, validation integration, CLI/templates, broader EF Core provider checks, and transition tooling. These will remain opt-in so the secure explicit core stays predictable.

Branding

The package icon is stored at assets/branding/astraflow-icon.png and is included in every NuGet package through PackageIcon.

Generator prompt:

Create a square app/package icon for a .NET library named AstraFlow. Use an abstract orbital star and flowing path motif that suggests explicit application flow, mediator dispatch, and auditable mapping. Keep it as a clean vector-friendly modern tech logo with crisp edges, centered symbol only, no text, strong silhouette readable at 64x64, generous padding, deep navy background with cyan, teal, white, and a small warm amber star accent. Avoid words, letters, code snippets, watermarks, photorealism, and complex gradients.

Repository Readiness

The package folder includes CI, a gated publish workflow, security policy, contributing guide, changelog, samples, and release checklist. Publishing should happen only after:

• package tests pass,
• representative consumer applications build against the package projects or packed packages successfully,
• package artifacts build with XML docs and symbols,
• the API surface is reviewed for v1 stability,
• NuGet Trusted Publishing is configured, or a scoped GitHub Actions publishing secret is configured in the release repository.

For first publish setup, create a dedicated GitHub repository, copy this folder into the repository root, configure Trusted Publishing or the documented GitHub secret, and run the gated publish workflow. See docs/publishing.md.

License

MIT.