An application layer for ASP.NET Core, one module at a time.

netfly’s modules authorize commands, cache queries, publish to Kafka or RabbitMQ, and run sagas and try-confirm-cancel steps, with Polly policies and JWT security. Event sourcing is optional.

  1. 01 Service composition
  2. 02 Domain boundaries
  3. 03 Business operations
  4. 04 History and projections
  5. 05 External integrations
  6. 06 Business coordination
  7. 07 Identity and resilience
  8. 08 Service operations
.NET 10 · C# · ASP.NET Core
Scroll to explore

Native stack and framework

What netfly adds to ASP.NET Core and EF Core.

ASP.NET Core hosts and routes the service, and EF Core persists its data. netfly’s starters register its modules through the host’s dependency injection, and the data layer stays your team’s.

Service composition

One of four starters registers a service’s modules for it.

With ASP.NET Core and EF Core alone, your team builds
Matching registrations in ASP.NET Core hosting, dependency injection, middleware, and configuration.
netfly provides
Core, Data, Domain, and Application starters that register module sets.
How it works

AddFireflyCore registers web, observability, cache, events, and CQRS. AddFireflyApplication adds resilience, security, actuator, scheduling, sessions, i18n, AOP, and WebSockets.

The starters leave out identity providers, orchestration, and rule engines. Register the ones your service uses.

See the implementation

Domain boundaries

Services code against netfly’s IRepository contract and keep their own EF Core configuration. Event-sourced ones also use its AggregateRoot.

With ASP.NET Core and EF Core alone, your team builds
Repository contracts and event-sourced aggregate conventions around your EF Core models.
netfly provides
Repository and filtering contracts and an event-sourced aggregate base. Your team writes the EF Core repositories.
How it works

IRepository defines find, save, delete, count, and paged queries. AggregateRoot applies changes, replays history, and tracks uncommitted events.

Your application registers its own DbContext, since the data starter registers none.

See the implementation

Business operations

Commands and queries are checked before their handlers, and cached results clear on the events you choose.

With ASP.NET Core and EF Core alone, your team builds
Validation, permission checks, query caching, and invalidation around every command and query handler.
netfly provides
Command and query buses with authorization and query caching, plus attribute rules for cache invalidation.
How it works

DefaultQueryBus authorizes a query, then serves a cacheable result from the cache or stores the handler’s answer. EventDrivenCacheInvalidator clears the cache patterns that [InvalidateCacheOn] names.

Your application delivers events to the cache invalidator.

See the implementation

History and projections

An event-sourced service writes its events once and builds delivery and read models from them.

With ASP.NET Core and EF Core alone, your team builds
Event versions, atomic event and outbox writes, a relay, and projection checkpoints.
netfly provides
An EF Core event store with an outbox, an outbox relay, snapshots, and a projection runner.
How it works

ProjectionRunner applies upcasters and projections from each checkpoint, and an EF Core store keeps snapshots. The relay and projections are hosted services.

The domain starter uses an in-memory event store, and the checkpoint store is in memory too.

See the implementation

External integrations

Events go out through IEventPublisher to Kafka, RabbitMQ, or an in-process channel.

With ASP.NET Core and EF Core alone, your team builds
Kafka, RabbitMQ, and vendor SDK calls behind your own contracts and outbound policies.
netfly provides
Kafka and RabbitMQ publishers and consumers, a resilient publisher, and SendGrid and S3 adapters.
How it works

ResilientEventPublisher wraps any publisher in Polly retry, circuit-breaker, and timeout policies. The Kafka publisher enables idempotent production and waits for all replicas.

Publishers and consumers are configured separately: the Kafka publisher leaves the in-memory consumer in place.

See the implementation

Business coordination

A recovery service finds stale runs of the saga, workflow, and try-confirm-cancel engines.

With ASP.NET Core and EF Core alone, your team builds
Step ordering, compensation, participant coordination, and recovery in your own hosted services.
netfly provides
Saga, workflow, and TCC engines, with a recovery service that finds stale executions.
How it works

TccEngine runs every Try, then confirms. A failed Try cancels the participants already tried. WorkflowEngine runs ordered steps with timers and signals.

The provided execution store is in memory. Supply your own for runs that must survive a restart. A failed TCC confirmation is recorded, not rolled back.

See the implementation

Identity and resilience

Your code reads the request’s user and tenant from a security context and runs calls through named Polly pipelines.

With ASP.NET Core and EF Core alone, your team builds
JwtBearer settings, identity-provider clients, and Polly policies, kept aligned.
netfly provides
JWT bearer configuration, a security-context holder, identity adapters, and named Polly policies.
How it works

AddFireflySecurity configures ASP.NET Core’s JwtBearer authentication from Firefly options. AddFireflyResilience builds named retry, breaker, rate-limit, bulkhead, and timeout pipelines.

Validate the tenant at a trusted boundary: SecurityContextMiddleware takes X-Tenant-Id straight from the request.

See the implementation

Service operations

Core services export OTLP telemetry. The Application starter adds actuator endpoints, and the admin client can register the service with an admin server.

With ASP.NET Core and EF Core alone, your team builds
Exporter setup, health and management endpoints, and a registry your services report to.
netfly provides
Firefly meters and runtime metrics, and an admin client that sends heartbeats and unregisters on shutdown.
How it works

Observability registers Firefly meters and sources, runtime metrics, and OTLP exporters. AdminClientHostedService registers the service, sends heartbeats, and unregisters on shutdown.

netfly doesn’t instrument HTTP or database calls. Secure the actuator endpoints yourself.

See the implementation
Already in the native stack
ASP.NET Core provides hosting, dependency injection, routing, authorization policies, error handling, and caching. EF Core provides persistence and database transactions.
Your team still owns
Validation and authorization rules, command handlers, domain behavior, persistence, and the execution context. The data starter expects your own DbContext, and the Orders sample uses an in-memory repository.

Stored events

An aggregate’s stored events feed a relay and your projections.

An aggregate’s events and their outbox rows commit together.

How EfCoreEventStore commits an aggregate’s events

  1. Your aggregate produces domain events.
  2. EfCoreEventStore checks the version and writes event and outbox rows in one transaction.

Deliver committed events

  1. The outbox holds unsent rows.
  2. A hosted relay publishes them through the event publisher.
  3. A sent row is marked afterward, so consumers must tolerate redelivery.

Build read models

  1. Projection runners read stored events from their checkpoints.
  2. Upcasters and your projections process each event.
  3. The checkpoint store records each projection’s progress.

Ordinary repository writes don’t reach the outbox. Only EfCoreEventStore writes there.

Capabilities

Pick the modules your service needs.

netfly / Conceptual architectureThe error middleware wraps command dispatch, and sagas, caching, and events are separate modules.

Amber: Firefly modulesIvory lines: APIsAmber lines: events

Validated command dispatch

The command bus runs each command’s validation and authorization, then resolves and invokes its registered handler.

See the source

Attribute-based sagas

SagaEngine orders [SagaStep] methods by their dependencies. When a step fails, it calls the completed steps’ compensation methods in reverse.

See the source

Structured HTTP errors

The error middleware turns exceptions into problem responses with a status, an error code, a trace id, and a correlation id.

See the source

In-process caching

The memory cache adapter reads, writes, and evicts values, including every key under a prefix.

See the source

In-process event delivery

The in-memory publisher writes event envelopes to a channel per destination, and consumers read them in the same process.

See the source

Code

Load an order with a netfly query handler.

GetOrderHandler takes its repository as a primary-constructor parameter and loads an order by id. It maps the order to an OrderDto, or returns null when none exists.

Follow an order through the sample

  1. Register the modules

    AddFireflyCore registers web, observability, cache, events, and CQRS, then the sample adds its repository.

    See the source
  2. Send a command

    The POST /api/v1/orders endpoint sends a PlaceOrderCommand through the command bus, with a demo user and tenant.

    See the source
  3. Test the dispatch

    The bus tests send a command to its handler and expect a validation failure for an empty one.

    See the source
GetOrderHandler.cs
using FireflyFramework.Cqrs.Queries;
using FireflyFramework.Samples.OrdersService.Core.Mappers;
using FireflyFramework.Samples.OrdersService.Interfaces.Dtos.V1;
using FireflyFramework.Samples.OrdersService.Models.Repositories;
using ExecutionContext = FireflyFramework.Cqrs.Context.ExecutionContext;

namespace FireflyFramework.Samples.OrdersService.Core.Services.Orders.V1;

public sealed class GetOrderHandler(IOrderRepository repository) : IQueryHandler<GetOrderQuery, OrderDto?>
{
    public async Task<OrderDto?> HandleAsync(GetOrderQuery query, ExecutionContext context, CancellationToken ct = default)
    {
        var entity = await repository.GetAsync(query.OrderId, ct).ConfigureAwait(false);
        return entity?.ToDto();
    }
}

Checks that run before the handler

DefaultCommandBus runs the command’s validation, then its authorization, and throws before resolving any handler. Both hooks allow everything until your commands define the rules.

DefaultCommandBus.cs
        var validation = await command.ValidateAsync(ct).ConfigureAwait(false);
        if (!validation.IsValid)
        {
            throw new CqrsValidationException("Command validation failed", validation.Failures);
        }

        var auth = await command.AuthorizeAsync(context, ct).ConfigureAwait(false);
        if (!auth.IsAllowed)
        {
            throw new CqrsAuthorizationException(
                string.Join("; ", auth.Errors.Select(e => $"{e.Code}: {e.Message}")), auth.Errors);
        }

Setup

Build netfly from its source workspace.

Register your command assemblies and the starters you need in a .NET 10 application. Because the buses are singletons, scope each handler’s DbContext deliberately.

netfly has no public release tag. CI built, tested, and packed the pinned commit.

The error middleware maps CQRS validation and authorization failures to HTTP 500. Map them to 400 and 403 in your host.

Next step

Read the Orders service sample.