SourceFlow.Cloud.Azure 2.0.0-beta.1

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher.
This is a prerelease version of SourceFlow.Cloud.Azure. 
dotnet add package SourceFlow.Cloud.Azure --version 2.0.0-beta.1
                    


                    

                
NuGet\Install-Package SourceFlow.Cloud.Azure -Version 2.0.0-beta.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="SourceFlow.Cloud.Azure" Version="2.0.0-beta.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="SourceFlow.Cloud.Azure" Version="2.0.0-beta.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="SourceFlow.Cloud.Azure" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add SourceFlow.Cloud.Azure --version 2.0.0-beta.1
                    


                    

                
#r "nuget: SourceFlow.Cloud.Azure, 2.0.0-beta.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package SourceFlow.Cloud.Azure@2.0.0-beta.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=SourceFlow.Cloud.Azure&version=2.0.0-beta.1&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=SourceFlow.Cloud.Azure&version=2.0.0-beta.1&prerelease
                    


                            Install as a Cake Tool

SourceFlow.Cloud.Azure

Azure cloud integration for distributed command and event processing

NuGet License

Overview

SourceFlow.Cloud.Azure extends the SourceFlow.Net framework with Azure cloud services integration, enabling distributed command and event processing using Azure Service Bus and Azure Key Vault. This package provides production-ready dispatchers, listeners, and configuration for building scalable, cloud-native event-sourced applications. The fluent bus API is identical to the AWS provider โ€” only the backing services change.

Key Features:

  • ๐Ÿš€ Azure Service Bus command dispatching with session-based ordering
  • ๐Ÿ“ข Azure Service Bus topic/subscription event publishing with fan-out
  • ๐Ÿ” Azure Key Vault envelope encryption for sensitive data
  • โš™๏ธ Fluent bus configuration API
  • ๐Ÿ”„ Automatic resource provisioning (queues, topics, subscriptions)
  • ๐Ÿ“Š Built-in observability and health checks
  • ๐Ÿงช Service Bus emulator integration for local development

Table of Contents

  1. Installation
  2. Quick Start
  3. Configuration
  4. Azure Services
  5. Bus Configuration System
  6. Message Encryption
  7. Idempotency
  8. Local Development
  9. Monitoring
  10. Best Practices

Installation

NuGet Package

dotnet add package SourceFlow.Cloud.Azure

Prerequisites

  • SourceFlow >= 2.0.0
  • Azure SDK for .NET (Service Bus, Identity, Key Vault)
  • .NET 8.0, .NET 9.0, or .NET 10.0

Quick Start

using SourceFlow.Cloud.Azure;

// Register SourceFlow core
services.UseSourceFlow(typeof(Program).Assembly);

// Configure Azure cloud messaging
services.UseSourceFlowAzure(
    options =>
    {
        options.ServiceBusConnectionString = configuration["Azure:ServiceBus:ConnectionString"];
    },
    bus => bus
        .Send
            .Command<CreateOrderCommand>(q => q.Queue("orders"))
            .Command<ProcessPaymentCommand>(q => q.Queue("payments"))
        .Raise
            .Event<OrderCreatedEvent>(t => t.Topic("order-events"))
            .Event<PaymentProcessedEvent>(t => t.Topic("payment-events"))
        .Listen.To
            .CommandQueue("orders")
            .CommandQueue("payments")
        .Subscribe.To
            .Topic("order-events")
            .Topic("payment-events"));

This registers Azure dispatchers, configures routing, starts Service Bus listeners, and automatically provisions queues/topics/subscriptions at startup.

Passwordless authentication

Instead of a connection string, set SourceFlow:Azure:ServiceBus:FullyQualifiedNamespace (e.g. myns.servicebus.windows.net) to authenticate with DefaultAzureCredential (Managed Identity, Azure CLI, Visual Studio, etc.).

Configuration

Connection settings are read from configuration when not supplied via options:

Key Description
SourceFlow:Azure:ServiceBus:ConnectionString Service Bus connection string
SourceFlow:Azure:ServiceBus:FullyQualifiedNamespace Namespace for Managed Identity auth
Option Type Default Description
ServiceBusConnectionString string null Service Bus connection string
EnableCommandRouting bool true Enable command dispatching to queues
EnableEventRouting bool true Enable event publishing to topics
EnableCommandListener bool true Enable queue command processors
EnableEventListener bool true Enable topic subscription processors

Azure Services

  • Azure Service Bus queues โ€” command dispatching with SessionId (entity id) for strict FIFO ordering per entity, optional duplicate detection, and dead-letter queues.
  • Azure Service Bus topics/subscriptions โ€” event publishing with fan-out to multiple subscriptions; subscriptions forward to the listening command queue.
  • Azure Key Vault โ€” envelope encryption keys for message payload protection.

Bus Configuration System

The fluent BusConfigurationBuilder is shared with the rest of SourceFlow.Net:

bus => bus
    .Send.Command<CreateOrderCommand>(q => q.Queue("orders"))
    .Raise.Event<OrderCreatedEvent>(t => t.Topic("order-events"))
    .Listen.To.CommandQueue("orders")
    .Subscribe.To.Topic("order-events");

Message Encryption

Enable envelope encryption for sensitive message payloads backed by Azure Key Vault:

services.AddSingleton<IMessageEncryption>(sp =>
    new AzureKeyVaultMessageEncryption(
        keyVaultUrl: "https://my-vault.vault.azure.net/",
        keyName:     "sourceflow-key",
        credential:  new DefaultAzureCredential()));

services.UseSourceFlowAzure(options => ..., bus => ...);

Encryption flow: Generate data key โ†’ Encrypt message with AES-GCM (data key) โ†’ Wrap data key with the Key Vault master key โ†’ Store in the Service Bus message.

Idempotency

  • In-memory (single instance) โ€” registered by default as a singleton with a background cleanup service. Suitable for single-instance deployments.
  • SQL-based (multi-instance / production) โ€” install SourceFlow.Stores.EntityFramework and call services.AddSourceFlowIdempotency(connectionString, cleanupIntervalMinutes) before UseSourceFlowAzure(...).

โš ๏ธ Always use SQL-based idempotency for multi-instance deployments โ€” the in-memory store lives in a single process and is insufficient for distributed systems.

Local Development

Azurite emulates Blob/Queue/Table storage but not Service Bus. For local development and CI, use the official Azure Service Bus emulator (backed by SQL Edge), declaring your entities up front in its Config.json:

docker compose -f .github/azure-emulator/docker-compose.yml up -d

export AZURE_SERVICEBUS_CONNECTION_STRING="Endpoint=sb://localhost;\
SharedAccessKeyName=RootManageSharedAccessKey;\
SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true"

The emulator serves only entities declared in Config.json (no runtime creation) and caps total queues + topics at 50.

Monitoring

  • Activity Source: SourceFlow.Cloud.Azure
  • Health check: registered automatically as azure-servicebus (tags: azure, servicebus, messaging), covering namespace connectivity, queue/topic existence, and Key Vault access when encryption is enabled.
  • Trace context is propagated via the Service Bus message ApplicationProperties (traceparent) for end-to-end distributed tracing.

Best Practices

  • Use sessions for ordered operations (the dispatcher sets SessionId = entity id).
  • Enable duplicate detection on queues fed by at-least-once producers.
  • Group related commands to the same queue (CreateOrder, UpdateOrder, CancelOrder โ†’ orders).
  • Enable SQL-based idempotency in production.
  • Prefer Managed Identity (FullyQualifiedNamespace + RBAC) over connection strings.
  • Enable Key Vault encryption for PII, financial, or health data.
  • Use IaC (Bicep/Terraform) for production resources; the bootstrapper is for dev convenience.
  • Monitor health checks and dead-letter queue depth.

License

MIT โ€” see LICENSE.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.0-beta.1 42 6/25/2026

v2.0.0 - Major release with production-ready Azure integration.
     - Service Bus command dispatching: queues with session-based ordering and duplicate detection.
     - Service Bus event publishing: topic creation, subscription management, and fan-out.
     - Bus bootstrapper: IHostedService that auto-provisions queues, topics, and subscriptions at startup.
     - Security: Azure Key Vault envelope encryption for messages, sensitive data masking in logs.
     - Resilience: circuit breaker, configurable retry policies, and throttling protection.
     - Dead letter queues: automatic DLQ handling and failed message reprocessing.
     - Health checks: IHealthCheck implementation for the Service Bus namespace.
     - Observability: OpenTelemetry distributed tracing across command and event flows.
     - Breaking change: depends on SourceFlow.Net 2.0.0 (Cloud.Core consolidated into core).