The Azure LoanBroker showcase is a comprehensive loan broker implementation following the structure presented by Gregor Hohpe in his Enterprise Integration Pattern book.
Note
The showcase runs locally using Docker, however, due to connection limitations with the Azure Service Bus Emulator, an Azure account is needed for the default setup. The how to run the example section details how to configure the solution to connect to Azure services. A separate Docker Compose file is available for running the solution using the Azure Service Bus Emulator, but this is a cut down version of the showcase that does not demonstrate the full functionality of NServiceBus.
This is the logical architecture:
And this is how that is represented using Azure services running locally:
The example is composed by:
- A client application, sending loan requests.
- A credit bureau providing the customers' credit score.
- A loan broker service that receives loan requests enriches them with credit scores and orchestrates communication with downstream banks.
- Three bank adapters, acting like Anti-Corruption layers (ACL), simulate communication with downstream banks offering loans.
- An email sender simulating email communication with customers.
The example also ships the following monitoring services:
- The Particular platform to monitor endpoints, capture and visualize audit messages, and manage failed messages.
- A Prometheus instance to collect, store, and query raw metrics data.
- A Grafana instance with three different metrics dashboards using Prometheus as the data source.
- A Jaeger instance to visualize OpenTelemetry traces.
- OpenTelemetry collector to collect and export metrics and traces to various destinations.
- .NET 10 SDK
- Docker
- Docker Compose
The simplest way to run the example is using Docker for both the endpoints and the infrastructure. The client application, the loan broker service, the e-mail sender, and the bank adapters can be deployed as Docker containers alongside the Particular platform to monitor the system, Azure Service Bus for messaging, SQL Server for persistence, and the additional containers needed for enabling OpenTelemetry observability.
Before running the complete example in Docker, create a local .env file from .env.example in the root folder and set AZURE_SERVICE_BUS_CONNECTION_STRING with your Azure Service Bus connection string.
Note
The .env file is local only and should not be committed.
To run the complete example in Docker, publish the endpoint container images and start the Compose environment from the root folder:
The initial run will pull several containers required to run the demo. See Ports for the host ports these containers expose — make sure they are free before starting.
dotnet publish src/AzureLoanBrokerShowcase.slnx -c Release --os linux /t:PublishContainer
docker compose up -dTip
Once the project is running, check out the Things to try section.
The dotnet publish command builds projects and publishes Linux container images to the local Docker registry using the .NET SDK built-in container support. The Docker Compose command starts those endpoint images and configures all the additional infrastructural containers.
To stop the running solution and remove all deployed containers. Using a command prompt, execute the following command:
docker compose downTo run the solution without rebuilding container images, execute the following command:
docker compose up -dTo run the cut down version of the showcase with the Azure Service Bus Emulator, execute the following command from the root folder:
dotnet publish src/AzureLoanBrokerShowcase.slnx -c Release --os linux /t:PublishContainer
docker compose -f docker-compose-ASB-emulator.yml up -dTo stop the emulator-based solution and remove all deployed containers, execute the following command:
docker compose -f docker-compose-ASB-emulator.yml downNote
The emulator-based setup is a cut down version of the showcase and excludes Bank2 due to the Azure Service Bus Emulator connection limits. Microsoft has confirmed there are currently no plans to increase these limits: Azure/azure-service-bus-emulator-installer#58 (comment)
If you prefer to start the endpoints from your IDE to debug the code, execute the following command from a command prompt in the root directory to start the required infrastructure:
docker compose --profile infrastructure up -dThe endpoint containers (Client, LoanBroker, Bank1/2/3, EmailSender) do not expose host ports — they communicate over Azure Service Bus. The infrastructure containers expose the following ports on the host. Make sure these are free before starting the demo.
| Port | Service |
|---|---|
| 1433 | SQL Server (NServiceBus persistence) |
| 3000 | Grafana |
| 4317 | OpenTelemetry Collector — OTLP gRPC |
| 5318 | OpenTelemetry Collector — OTLP HTTP |
| 1234 | OpenTelemetry Collector — Prometheus endpoint |
| 7071 | Credit Bureau (Azure Functions worker) |
| 8080 | ServiceControl RavenDB Studio |
| 9090 | Prometheus |
| 9999 | ServicePulse UI |
| 16686 | Jaeger UI |
| 33333 | ServiceControl API |
| 33633 | ServiceControl Monitoring API |
| 44444 | ServiceControl Audit API |
The emulator-based setup omits the Particular platform containers (ServiceControl, ServiceControl Audit, ServiceControl Monitoring, ServicePulse) and adds the emulator itself.
| Port | Service |
|---|---|
| 1433 | SQL Server |
| 3000 | Grafana |
| 4317 | OpenTelemetry Collector — OTLP gRPC |
| 5318 | OpenTelemetry Collector — OTLP HTTP |
| 1234 | OpenTelemetry Collector — Prometheus endpoint |
| 5300 | Azure Service Bus Emulator (management) |
| 5672 | Azure Service Bus Emulator (AMQP) |
| 7071 | Credit Bureau |
| 9090 | Prometheus |
| 16686 | Jaeger UI |
Once the project is running, here are some things to try. (Links are to localhost and will only work when the project is running.)
- Explore some traces in the Jaeger UI.
- The green circles are traces where the entire flow completed successfully.
- The red circles are traces that contain an exception at some point. (Bank3 fails 1/3 of the time.) Click into the failed steps and find the exception message and stack trace in the logs.
- Check out a selection of business metrics in Grafana. (User
adminand passwordadmin.)- Some metrics are available for individual message types, even though the messages are processed from the same message queue.
- Many more metrics are available by navigating to Dashboards and selecting a different dashboard.
- Explore the ServicePulse endpoint monitoring dashboard, then navigate to LoanBroker to see how these metrics are available for individual message types as well.
- Investigate the EmailSender failures (the code is rigged to fail 5% of the time) in the ServicePulse Failed Messages view.
- Navigate into the failed message group, then to an individual message.
- Click on the tabs to see how the stack trace, message headers, and message body help a developer to troubleshoot and fix systemic errors.
- Return to the failed message groups view and request a retry for the entire batch of failed messages.
- The message handler will still fail 5% of the time. Click into the message group and see if there are any messages showing Retry Failures.
The example comes with the Particular platform, automatically available as Docker containers.
Monitoring information is available in ServicePulse.
NServiceBus supports OpenTelemetry. Starting with NServiceBus 9.1, the following metrics are available:
nservicebus.messaging.successes- Total number of messages processed successfully by the endpointnservicebus.messaging.fetches- Total number of messages fetched from the queue by the endpointnservicebus.messaging.failures- Total number of messages processed unsuccessfully by the endpointnservicebus.messaging.handler_time- The time the user handling code takes to handle a messagenservicebus.messaging.processing_time- The time the endpoint takes to process a messagenservicebus.messaging.critical_time- The time between when a message is sent and when it is fully processednservicebus.recoverability.immediate- Total number of immediate retries requestednservicebus.recoverability.delayed- Total number of delayed retries requestednservicebus.recoverability.error- Total number of messages sent to the error queue
For more information, refer to the NServiceBus OpenTelemetry documentation.
All endpoints are configured to send OpenTelemetry traces to Jaeger. To visualize traces, open the Jaeger dashboard.
Similarly, endpoints send metrics to Prometheus. To visualize metrics, open the Grafana dashboards. The default Grafana credentials are:
- Username:
admin - Password:
admin
Note
Setting a new password can be skipped. When containers are redeployed, the credentials are reset to their default values.
The example deploys three pre-configured Grafana dashboards:
- The LoanBroker dashboard shows various metrics about the business endpoints behavior, such as the differences between the services critical, processing, and handling time.
- The Loan Broker Demo dashboard highlights a curated set of business metrics broken down by individual message type, useful for walking through the showcase.
- The NServiceBus dashboard shows the metrics related to message fetches, processing, and failures, grouped by endpoints or message type.
Note
After running the solution multiple times, it might happen that Grafana suddenly shows random data instead of the expected metrics. To reset dashboards, tear down all containers and delete the data-grafana and data-prometheus folders from the solution folder. Redeploy the containers.