Benzene.Abstractions 0.0.2-alpha.3

Benzene — .NET

This is the .NET port of Benzene. Benzene is defined by a language-neutral specification that lives in the cross-language benzene repo, alongside the project website. This repo is the C# implementation of that spec — its packages, examples, templates, and .NET how-to docs. ".NET" is one language port; others translate the same spec.

Benzene is a hexagonal (ports-and-adapters) framework for C# built around a shared middleware pipeline — write your message handlers and cross-cutting concerns (logging, correlation IDs, validation, health checks) once, then run the same service behind AWS Lambda (API Gateway, SQS, SNS, Kafka, EventBridge), Azure Functions (HTTP, Event Hubs, Service Bus, Cosmos DB Change Feed, Queue/Blob Storage, Event Grid, Timer), or ASP.NET Core without rewriting any of it.

Why Benzene?

• Write a message handler once, against a topic — swap the transport (HTTP, Lambda, SQS, SNS, Kafka...) without touching handler code
• Cross-cutting concerns (correlation IDs, logging, validation, health checks) live in composable middleware, not scattered across handlers
• New message handlers are discovered automatically by reflection — no manual routing tables to maintain
• Multi-cloud by design: the same handlers run on AWS, Azure, or a plain ASP.NET Core host
• Honest by design: Benzene abstracts your business logic, never the transport or the database — so you keep every cloud-native feature of the tools you chose (see the Capability Matrix)
• Designed to outlive its .NET implementation: every concept, wire format, and status is written down independently of the C# API, so a future port to another language is a translation of a design, not a rewrite (see the Benzene Specification, the cross-language source of truth in the benzene repo)

Quickstart

Benzene's packages are published as prerelease (-alpha) versions until 1.0, so --prerelease is required:

dotnet add package Benzene.AspNet.Core --prerelease

A message handler, mapped to a topic:

[Message("hello:world")]
[HttpEndpoint("GET", "/hello/{name}")]
public class HelloWorldMessageHandler : IMessageHandler<HelloWorldRequest, HelloWorldResponse>
{
    public Task<IBenzeneResult<HelloWorldResponse>> HandleAsync(HelloWorldRequest message)
    {
        return Task.FromResult(BenzeneResult.Ok(new HelloWorldResponse { Message = $"Hello {message.Name}!" }));
    }
}

Wired into an ASP.NET Core host (in Program.cs):

var builder = WebApplication.CreateBuilder(args);

builder.Services.UsingBenzene(x => x
    .AddMessageHandlers(typeof(HelloWorldMessageHandler).Assembly));

var app = builder.Build();

app.UseBenzene(benzene => benzene
    .UseHttp(http => http
        .UseMessageHandlers()));

app.Run();

See Getting Started for the full five-minute walkthrough (including the request/response message types omitted above for brevity), and examples/ for complete, runnable sample projects covering AWS Lambda, Azure Functions, ASP.NET Core, Kafka, and more.

How it fits into hexagonal architecture

Your message handlers are the application core — they depend only on Benzene.Abstractions types (IMessageHandler<TRequest, TResponse>, IBenzeneResult<T>) and whatever port interfaces you define for your own dependencies (databases, other services). Each transport (Benzene.AspNet.Core, Benzene.Aws.Lambda.*, Benzene.Azure.*) is an adapter that converts its native request into a message and routes it to the matching handler via UseMessageHandlers(), then converts the IBenzeneResult back into a transport-native response. Middleware in Benzene.Core.Middleware provides the pipeline that every adapter shares, so correlation IDs, logging, validation, and health checks are written once and apply everywhere.

Documentation

Full .NET documentation is available in docs/, including:

• Message Handlers and Handler Results
• Middleware and Common Middleware
• Testing Benzene
• Health Checks and Monitoring & Diagnostics
• AWS Lambda Setup
• Azure Functions Setup
• ASP.NET Core Integration
• Fluent Validation and Data Annotations
• Terraform Code Generation and OpenAPI/AsyncAPI Spec
• Correlation IDs

The language-neutral specification (concepts, wire contracts, transport bindings, conformance fixtures, porting guide) is not here — it is the cross-language source of truth and lives in the benzene repo. This repo vendors a snapshot of the conformance fixtures under test/conformance-fixtures/ (kept in sync by the conformance-drift-check CI job) so the test suite is self-contained.

Installation

dotnet add package Benzene.Core --prerelease

Plus whichever transport and integration packages your service needs (Benzene.AspNet.Core, Benzene.Aws.Lambda.ApiGateway, Benzene.Azure.Function.Core, Benzene.FluentValidation, etc.) — see docs/ for the relevant package per adapter.

Requires .NET 10.

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup, conventions, and what to read before sending a change.

License

MIT — see LICENSE for details.