From e6a80c0380c0b54f8a7cac11c6196a6d096ed2e6 Mon Sep 17 00:00:00 2001 From: Gideon de Swardt Date: Sat, 3 Apr 2021 23:19:24 +0100 Subject: [PATCH] Add documentation Added documentation on how to configure and setup the Azure Service Bus as the Distributed Event Bus. --- ...Distributed-Event-Bus-Azure-Integration.md | 133 ++++++++++++++++++ docs/en/Distributed-Event-Bus.md | 1 + docs/en/docs-nav.json | 4 + 3 files changed, 138 insertions(+) create mode 100644 docs/en/Distributed-Event-Bus-Azure-Integration.md diff --git a/docs/en/Distributed-Event-Bus-Azure-Integration.md b/docs/en/Distributed-Event-Bus-Azure-Integration.md new file mode 100644 index 0000000000..ca66cbca8a --- /dev/null +++ b/docs/en/Distributed-Event-Bus-Azure-Integration.md @@ -0,0 +1,133 @@ +# Distributed Event Bus Azure Integration + +> This document explains **how to configure the [Azure Service Bus](https://azure.microsoft.com/en-us/services/service-bus/)** as the distributed event bus provider. See the [distributed event bus document](Distributed-Event-Bus.md) to learn how to use the distributed event bus system + +## Installation + +Use the ABP CLI to add [Volo.Abp.EventBus.Azure](https://www.nuget.org/packages/Volo.Abp.EventBus.Azure) NuGet package to your project: + +* Install the [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) if you haven't installed before. +* Open a command line (terminal) in the directory of the `.csproj` file you want to add the `Volo.Abp.EventBus.Azure` package. +* Run `abp add-package Volo.Abp.EventBus.Azure` command. + +If you want to do it manually, install the [Volo.Abp.EventBus.Azure](https://www.nuget.org/packages/Volo.Abp.EventBus.Azure) NuGet package to your project and add `[DependsOn(typeof(AbpEventBusAzureModule))]` to the [ABP module](Module-Development-Basics.md) class inside your project. + +## Configuration + +You can configure using the standard [configuration system](Configuration.md), like using the `appsettings.json` file, or using the [options](Options.md) classes. + +### `appsettings.json` file configuration + +This is the simplest way to configure the Azure Service Bus settings. It is also very strong since you can use any other configuration source (like environment variables) that is [supported by the AspNet Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/). + +**Example: The minimal configuration to connect to Azure Service Bus Namespace with default configurations** + +````json +{ + "Azure": { + "ServiceBus": { + "Connections": { + "Default": { + "ConnectionString": "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName={{Policy Name}};SharedAccessKey={};EntityPath=marketing-consent" + } + } + }, + "EventBus": { + "ConnectionName": "Default", + "SubscriberName": "MySubscriberName", + "TopicName": "MyTopicName" + } + } +} +```` + +* `MySubscriberName` is the name of this subscription, which is used as the **Subscriber** on the Azure Service Bus. +* `MyTopicName` is the **topic name**. + +See [the Azure Service Bus document](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions) to understand these options better. + +#### Connections + +If you need to connect to another Azure Service Bus Namespace the Default, you need to configure the connection properties. + +**Example: Declare two connections and use one of them for the event bus** + +````json +{ + "Azure": { + "ServiceBus": { + "Connections": { + "Default": { + "ConnectionString": "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey={{SharedAccessKey}}" + }, + "SecondConnection": { + "ConnectionString": "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName={{Policy Name}};SharedAccessKey={{SharedAccessKey}}" + } + } + }, + "EventBus": { + "ConnectionName": "SecondConnection", + "SubscriberName": "MySubscriberName", + "TopicName": "MyTopicName" + } + } +} +```` + +This allows you to use multiple Azure Service Bus namespaces in your application, but select one of them for the event bus. + +You can use any of the [ServiceBusAdministrationClientOptions](https://docs.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.administration.servicebusadministrationclientoptions?view=azure-dotnet), [ServiceBusClientOptions](https://docs.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusclientoptions?view=azure-dotnet), [ServiceBusProcessorOptions](https://docs.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusprocessoroptions?view=azure-dotnet) properties for the connection. + +**Example: Specify the Admin, Client and Processor options** + +````json +{ + "Azure": { + "ServiceBus": { + "Connections": { + "Default": { + "ConnectionString": "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName={{Policy Name}};SharedAccessKey={};EntityPath=marketing-consent", + "Admin": { + "Retry": { + "MaxRetries": 3 + } + }, + "Client": { + "RetryOptions": { + "MaxRetries": 1 + } + }, + "Processor": { + "AutoCompleteMessages": true, + "ReceiveMode": "ReceiveAndDelete" + } + } + } + }, + "EventBus": { + "ConnectionName": "Default", + "SubscriberName": "MySubscriberName", + "TopicName": "MyTopicName" + } + } +} +```` + +### The Options Classes + +`AbpAzureServiceBusOptions` and `AbpAzureEventBusOptions` classes can be used to configure the connection strings and event bus options for Azure Service Bus. + +You can configure this options inside the `ConfigureServices` of your [module](Module-Development-Basics.md). + +**Example: Configure the connection** + +````csharp +Configure(options => +{ + options.Connections.Default.ConnectionString = "Endpoint=sb://sb-my-app.servicebus.windows.net/;SharedAccessKeyName={{Policy Name}};SharedAccessKey={}"; + options.Connections.Default.Admin.Retry.MaxRetries = 3; + options.Connections.Default.Client.RetryOptions.MaxRetries = 1; +}); +```` + +Using these options classes can be combined with the `appsettings.json` way. Configuring an option property in the code overrides the value in the configuration file. diff --git a/docs/en/Distributed-Event-Bus.md b/docs/en/Distributed-Event-Bus.md index 02216c7ac8..70d5fbe391 100644 --- a/docs/en/Distributed-Event-Bus.md +++ b/docs/en/Distributed-Event-Bus.md @@ -7,6 +7,7 @@ Distributed Event bus system allows to **publish** and **subscribe** to events t Distributed event bus system provides an **abstraction** that can be implemented by any vendor/provider. There are two providers implemented out of the box: * `LocalDistributedEventBus` is the default implementation that implements the distributed event bus to work as in-process. Yes! The **default implementation works just like the [local event bus](Local-Event-Bus.md)**, if you don't configure a real distributed provider. +* `AzureDistributedEventBus` implements the distributed event bus with the [Azure Service Bus](https://azure.microsoft.com/en-us/services/service-bus/). See the [Azure Service Bus integration document](Distributed-Event-Bus-Azure-Integration.md) to learn how to configure it. * `RabbitMqDistributedEventBus` implements the distributed event bus with the [RabbitMQ](https://www.rabbitmq.com/). See the [RabbitMQ integration document](Distributed-Event-Bus-RabbitMQ-Integration.md) to learn how to configure it. * `KafkaDistributedEventBus` implements the distributed event bus with the [Kafka](https://kafka.apache.org/). See the [Kafka integration document](Distributed-Event-Bus-Kafka-Integration.md) to learn how to configure it. * `RebusDistributedEventBus` implements the distributed event bus with the [Rebus](http://mookid.dk/category/rebus/). See the [Rebus integration document](Distributed-Event-Bus-Rebus-Integration.md) to learn how to configure it. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index efca73a484..77c1476735 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -296,6 +296,10 @@ "text": "Distributed Event Bus", "path": "Distributed-Event-Bus.md", "items": [ + { + "text": "Azure Service Bus Integration", + "path": "Distributed-Event-Bus-Azure-Integration.md" + }, { "text": "RabbitMQ Integration", "path": "Distributed-Event-Bus-RabbitMQ-Integration.md"