DEV Community: Felipe Mattioli

Improving Azure Service Bus Development with AsbFlow

Felipe Mattioli — Thu, 23 Oct 2025 11:47:56 +0000

Today, I’d like to introduce a clean and effective way to bring organization and clarity to your Azure Service Bus integrations.

If you’ve ever struggled to keep message producers and consumers organized — or found yourself repeatedly writing boilerplate code to handle message publishing, retries, or custom behaviors — AsbFlow was built to simplify that.

It provides a single, fluent, and centralized configuration for your Azure Service Bus setup, but it goes beyond that.

AsbFlow also abstracts many of the platform’s possibilities:

middlewares for producers and consumers, multiple message production modes, and other extensibility features — all ready to use out of the box.

The result is clarity, organization, and quality in your message-driven development — making distributed communication as intuitive as working with MediatR.

⚙️ Message Production Modes

When producing a message with ICommandProducer, AsbFlow provides different ways to publish it, depending on your use case.

Here’s what you can do:

📨 Basic message production Produce a simple command without any additional configuration. Ideal for straightforward scenarios where no metadata or delay is needed.

  await producer.ProduceCommandAsync(command, cancellationToken);

🕒 Delayed message production Define a delivery delay so the message becomes available for processing after a specific time. Useful for scheduling or deferring certain operations.,

await producer.ProduceCommandAsync(command, TimeSpan.FromMinutes(5), cancellationToken);

🧩 Production with application properties

await producer.ProduceCommandAsync(command, new Dictionary<string, object>
{
    { "Source", "CRM" },
    { "Priority", "High" }
}, cancellationToken);

🚀 Introducing AzureServiceBusFlow

AzureServiceBusFlow is an open-source library designed to improve the organization of producers and consumers when using Azure Service Bus.

The core idea is simple:

Have a single, fluent, and centralized place to configure all your producers and consumers — bringing outstanding clarity to your code.

You can refer to it as AzureServiceBusFlow or just AsbFlow, as you prefer.

⚙️ Getting Started

Everything starts with a basic configuration, where you set your Azure Service Bus connection string and define your producers and consumers.

builder.Services.AddAzureServiceBus(cfg => cfg
    .ConfigureAzureServiceBus(azureServiceBusConfig)
    .AddProducer<ExampleCommand1>(p => p
        .EnsureQueueExists("command-queue-one") // We support Queue and Topic
        .WithCommandProducer() // or WithEventProducer
        .ToQueue("command-queue-one")) // Or ToTopic
    .AddConsumer(c => c
        .FromQueue("command-queue-one") // Or FromTopic
        .AddHandler<ExampleCommand1, CommandExample1Handler>())
);

🧠 What’s happening here?

We’re injecting a producer that sends messages of type ExampleCommand1.
Whenever you need to publish a message, just inject ICommandProducer<ExampleCommand1> and call it.
A corresponding consumer listens to the same queue and processes messages with the defined handler.

This example is intentionally simple, but it captures the core idea.

To dive deeper, check the official docs and GitHub repository — they include a full Samples project to explore in more detail:

🔗 GitHub Repository

📘 Documentation

🧩 A Real Example in Production

Here’s a slightly more advanced setup from a real API, which produces multiple message types between different services.

⚙️ Configuration

As you saw before, it’s mandatory to provide the configurations related to your Azure Service Bus — settings like the messaging mode (ReceiveAndDelete, PeekLock), MaxConcurrentCalls, ConnectionString, and so on.

These configurations can be set either by directly instantiating the AzureServiceBusConfiguration class.

🔗 See full sample on GitHub

Or also by defining them in your appsettings.json file and mapping them to a configuration class.

// appsettings.json example
"AzureServiceBusConfigurationSettings": {
  "ConnectionString": "",
  "ServiceBusReceiveMode": "ReceiveAndDelete", // You can use PeekLock or ReceiveAndDelete, depending on your needs
  "MaxAutoLockRenewalDurationInSeconds": "1800", // Used when using PeekLock mode
  "MaxConcurrentCalls": "10"
}

🧠 Configuring the use of AsbFlow

After that, I configure everything inside an extension method that extends IServiceCollection.

This method is then called in Program.cs to set up the entire AsbFlow.

You can explore this in more detail by checking out the example available in the repository.

public static class AzureServiceBusExtensions
{
    public static IServiceCollection AddAzureServiceBusFlow(
        this IServiceCollection services,
        AzureServiceBusConfiguration azureServiceBusConfiguration) // receiving the mapped settings made above
    {
        services.AddAzureServiceBus(cfg => cfg
            .ConfigureAzureServiceBus(azureServiceBusConfiguration)
            .AddProducer<CpfValidationMessage>(p => p
                .WithCommandProducer()
                .ToQueue(conversationQueueName))
            .AddProducer<StartSimulationConversationMessage>(p => p
                .WithCommandProducer()
                .ToQueue(conversationQueueName))
            .AddProducer<SimulateAvailableFgtsBalanceMessage>(p => p
                .WithCommandProducer()
                .ToQueue(conversationQueueName))
            .AddProducer<PixValidationMessage>(p => p
                .WithCommandProducer()
                .ToQueue(conversationQueueName))
            .AddConsumer(c => c
                .FromQueue(conversationQueueName)
                .AddHandler<CpfValidationMessage, DocumentValidationMessageHandler>()
                .AddHandler<StartSimulationConversationMessage, StartSimulationConversationMessageHandler>()
                .AddHandler<PixValidationMessage, PixValidationMessageHandler>())
        );

        return services;
    }
}

Once that’s done, all I need to do is create the producer and the consumer.

💬 Producing a Message

public sealed class CpfValidationCommandHandler(ICommandProducer<CpfValidationMessage> commandProducer)
    : ICommandHandler<CpfValidationCommand, Result>
{
    public async Task<Result> HandleAsync(CpfValidationCommand message, CancellationToken cancellationToken = default)
    {       
        await commandProducer.ProduceCommandAsync(
            message.ToCpfDocumentValidationMessage(), 
            cancellationToken
        ); // ProduceCommandAsync expects a CpfDocumentValidationMessage

        return Result.Success();
    }
}

📥 Consuming a Message

public sealed partial class CpfValidationMessageHandler() : IMessageHandler<CpfValidationMessage>
{
    public async Task HandleAsync(
        CpfValidationMessage message, 
        ServiceBusReceivedMessage rawMessage, 
        CancellationToken cancellationToken)
    {        
        // Implement your custom logic for the consumed message here
    }
}

As APIs grow, they often produce and consume many message types — and keeping this configuration readable can be a challenge.

That’s where AsbFlow really shines.

🔧 What Else Can AsbFlow Do?

Beyond simplifying producers and consumers, AsbFlow provides several powerful features:

🧭 Supports both Queues and Topics
⚙️ Organizes Commands and Events
- Commands represent an action (create, update, delete)
- Events represent a change of state
🧩 Middleware Support (Before producing or consuming messages)
- Add global headers, execute custom logic, or extend behavior dynamically
🕒 Flexible Message Production
- Schedule delayed messages
- Add ApplicationProperties
- Or just send simple messages instantly

🏗️ In Production

AsbFlow is currently running in production and has been performing reliably, greatly helping to streamline message processing and maintain clean, organized code.

If this project sounds useful to you, I’d love for you to check it out — or even contribute by adding features or even improve what we have today :)

🔗 GitHub Repository

💡 Inspiration

This project was inspired by the idea behind KafkaFlow.

During some part of my carreer I worked on Farfetch, there I had the opportunity to work with KafkaFlow and really appreciated its architecture and design principles.

Later in my career, when I started working more closely with Azure Service Bus, I wanted to replicate some of those concepts in a similar way.

Of course, KafkaFlow is a much more mature project — it has existed for some years and has an community of contributors — but it was a inspiration to work better with AzureServiceBusFlow or gently AsbFlow.

Feijuca.Auth – Part 2: Configuring, Creating Realm, and using Feijuca.Auth.API

Felipe Mattioli — Fri, 11 Jul 2025 11:51:24 +0000

This is the second article in a series about using Feijuca.Auth.

If you landed directly on this post, I recommend reading the first part:

Part 1: Understanding and Configuring Feijuca.Auth

Introduction
In the first article, we introduced the Feijuca.Auth project—its purpose, concepts, Now we'll move forward to the configuration basics.

Prerequisites
Before we dive in, make sure you have the following running:

✅ Keycloak
You’ll need a Keycloak instance running—either locally or on a server. The official Docker image can be pulled from:
👉 https://www.keycloak.org/getting-started/getting-started-docker

✅ MongoDB
Feijuca.Auth uses MongoDB to store metadata about your Keycloak server—like its URL, client secret, and realm configuration.

⚠️ Note: Feijuca.Auth does not store any user data. You own the instance entirely—Feijuca.Auth only needs your connection string.

💡You can use mongodb atlas to create a free mongodb instance.

💡 You also can contribute and add support to the db from your choice.

Initial Setup
Once both Keycloak and MongoDB are running, follow this required configuration step before launching Feijuca.Auth:

🔗 Keycloak Mandatory Configuration Guide

This step teaches you how to configure a client in the master realm (the default Keycloak realm). This client will have permissions required to manage other realms via Feijuca.Auth.

For further technical details, you can always refer to the full documentation:

📘 Feijuca.Auth Docs – Getting Started

Running Feijuca.Auth
Once everything is configured, you can run Feijuca.Auth using Docker:

docker run \ -e ConnectionString="mongodb://<username>:<password>@<host>:<port>" \ -e DatabaseName="FeijucaAuth" \ coderaw/feijuca-auth-api:latest

💡 You can change the database name and connection string as needed.

What is Feijuca.Auth.API?
Feijuca.Auth.API exposes a RESTful API that simplifies Keycloak realm management. With this module, you can:

Create users, groups, roles
Manage clients and client scopes
Create and configure new realms

Initial Realm Setup Endpoint
Before doing anything else, you need to call the initial configuration endpoint. This step sets up the realm, client, user, and default settings needed by Feijuca.Auth to operate.

Here’s the required curl request:

curl https://localhost:7018/api/v1/configs/new-realm \ --request POST \ --header 'Content-Type: application/json' \ --data '{ "realmAdminUser": { "email": "", // Set admin user email "password": "" // Set admin user password }, "client": { "clientId": "feijuca-auth-api" // Must match the client name configured in the master realm }, "clientSecret": { "clientSecret": "secret-retrieved-from-client" // Paste the actual client secret here }, "serverSettings": { "url": "" // The URL of your running Keycloak instance, e.g., https://localhost:8080 }, "realm": { "name": "", // Name of the new realm, or an existing one "issuer": "serverSettings-url/realmname" } }'

This will return a success status code and a message confirming that the initial configuration is complete.

🔁 After executing this endpoint, you must restart the Feijuca.Auth container. On startup, it will load the configuration from MongoDB and initialize correctly.

What Does This Endpoint Do?
This endpoint handles the essential setup required for both the Feijuca.Auth.Api and the Feijuca.Auth NuGet package to function properly. One of its core responsibilities is enabling multitenancy support.

Feijuca automatically maps the tenant user attribute into the token payload, which is crucial for implementing tenant-based access control. Every new user created via Feijuca will have a default tenant assigned, which corresponds to the name of the realm in which the user is being created.

Behind the scenes, this endpoint performs several operations—such as creating clients, roles, default configurations, and mappings—so you don't have to worry about the heavy lifting. It streamlines the setup process, allowing you to start building with Feijuca.Auth right away.

What’s Next?
Once your realm is configured and the container is restarted, you’ll be able to use the REST endpoints provided by Feijuca.Auth to perform all sorts of operations in your realm(s).

In the next post, I’ll walk through how to protect your own API endpoints using Feijuca.Auth.

Stay Tuned
If you’re building multitenant applications or need a simplified way to manage realms via Keycloak, Feijuca.Auth is designed to help you do just that with minimal setup and full control.

➡️ Explore the documentation
➡️ Follow me on Dev.to to get updates on the next part!

Feijuca.Auth - Part 1: Tool Overview

Felipe Mattioli — Fri, 03 Jan 2025 13:47:32 +0000

This is the first post in a series where I’ll dive deeper into how to use Feijuca.Auth in real-world scenarios — from setup to advanced usage.

Feijuca.Auth is an open-source project built on top of Keycloak — a well-established authentication and authorization tool widely used and trusted by the developer community.

The goal of Feijuca.Auth is to make it easier to work with Keycloak in .NET environments, especially in multitenant scenarios. It provides a layer of abstraction with cleaner, more straightforward endpoints, helping to simplify some of the complexity found in Keycloak’s official documentation, which can often be confusing or hard to navigate.

Beyond handling authentication and authorization, Feijuca.Auth offers APIs that make it easier to interact with Keycloak features such as user creation, client management, role assignments, and more — all via accessible REST endpoints.
These actions can later be consumed within your .NET applications, as Feijuca.Auth also provides a NuGet package that enables several features such as authentication, authorization, and retrieving which tenant(s) a given token belongs to.

The project was initially created by Felipe Mattioli, a backend developer, and has been in active use for about a year. From the beginning, it has been validated in a real-world application with around 100 daily active users and integration across 9 different APIs, all relying on a secure and centralized identity platform.

If you're working with .NET and using (or planning to use) Keycloak, Feijuca.Auth can help streamline your setup and save time on repetitive integration work. The project is also open for contributions — so if you enjoy backend development and want to collaborate on something that’s being used in production, feel free to join in.

Feijuca.Auth also comes with robust and actively maintained documentation, which is constantly evolving. You can check it out here: https://fmattioli.github.io/Feijuca.Auth/docs/gettingStarted.html.
Feel free to ask questions, explore the project, and evaluate whether it fits your specific needs.