How it works

Ordered integrations with a history you can act on.

NimBus is a .NET integration platform on Azure Service Bus, with session ordering at each receiving endpoint, processing history in SQL Server or Cosmos DB, and an operator console for recovery. Deploy it in your own environment and connect applications through adapters.

How a message travels

Published once, routed by type, delivered in order

A publisher sends one event to its endpoint's topic. Routing rules forward a copy to every endpoint that consumes that type, the receiver hands it to your handler in session order, and each outcome is reported to the Resolver.

  1. Publish

    The producer sends one event to its own endpoint topic.

  2. Route

    Rules keyed on the event type forward a copy to each consuming endpoint. Forwarded copies are never forwarded again.

  3. Order

    Messages with the same session key are handled one at a time, in order.

  4. Handle

    Your handler processes the event.

  5. Settle

    The message completes, or follows one of the failure paths below.

The Resolver receives every outcome and keeps one queryable record of each message's status, from Pending to Completed or Failed.

Message flows in detail →

What sets it apart

Four things raw Service Bus doesn't hand you

Session-ordered processing

Messages sharing a key are handled strictly in order. A poison message blocks only its own session; the rest of the bus keeps moving.

The Resolver

One centralized record of every message's outcome, start to finish. The recorded processing history is queryable from the operator console.

Operator WebApp

A live console to watch flows and resubmit or skip stuck messages, so you recover from failures without a redeploy.

Declarative topology

You declare endpoints in code. NimBus provisions the topics, subscriptions, and routing rules to match, idempotently.

When a handler fails

Every failure has a defined path

What the handler throws decides where the message goes. You configure retry policies and failure classifiers; NimBus routes the rest.

  • Transient error

    The handler throws TransientException, for example after a timeout or a 503. The message is abandoned and Service Bus redelivers it.

    Redelivered
  • Permanent error

    A bad payload or an unrecoverable 4xx, classified as permanent. The message goes straight to the dead-letter queue without using retries.

    Dead-lettered
  • Unexpected error

    Any other exception fails the message and blocks its session. A matching retry policy schedules a retry; otherwise the session waits for an operator to resubmit or skip.

    Failed
  • Expected, harmless failure

    A failure classifier can discard it. The message completes without a retry or a dead-letter, and the session carries on.

    Skipped
  • Long-running work

    The handler hands the work off to an external system. The session waits, in order, until the work completes or fails.

    Pending handoff

Messages that arrive behind a blocked message are recorded as Deferred and replay in order once the session is unblocked. The Resolver's main statuses are Pending, Completed, Failed, Deferred, Dead-lettered, and Skipped.

Error handling in detail →

The pieces

The anatomy of a NimBus app

Configure the SDK, storage, pipeline, and receiver hosting through dependency injection. You bring the events and handlers; NimBus brings ordering, routing, storage, and recovery.

Events

Plain classes. [SessionKey] sets the ordering scope, and [Sensitive] masks a property for operators without PII access.

Endpoints & platform

Declare what each endpoint produces and consumes. The platform definition is the single source of topology truth.

Pluggable storage

SQL Server or Cosmos DB behind one contract, with a conformance suite keeping them honest.

Pipeline middleware

Logging, metrics, and validation are built in. An opt-in circuit breaker pauses an endpoint when its failure rate spikes.

Transactional outbox

Record outgoing messages in your SQL business transaction and dispatch them after commit. Handlers should remain idempotent.

Hosting & SDK

Run handlers in a .NET Worker or an Azure Function, registered with AddNimBusPublisher and AddNimBusSubscriber.

Agent-ready

A schema registry and REST agent API let AI agents join the bus; the operator MCP endpoint lets them investigate and recover failures.

Notifications

Failures, dead-letters, and session blocks fan out to webhook, Teams, or email channels.

Standing it up

One command, or your own pipeline

Azure infrastructureService Bus topologyApplications
  • nb setup chains Bicep infrastructure, topology provisioning, and app deployment, in that order.
  • The repository ships a GitHub Actions workflow that signs in with OIDC, with no stored secrets, and an Azure DevOps pipeline.
  • The Resolver runs on Flex Consumption by default, or on Elastic Premium; the management WebApp runs on App Service.

Deployment guide → · CLI reference → · Architecture → · Decision records →

Ready to try it?

The CRM/ERP sample runs the whole platform on your machine, with no Azure account needed.