How to work with Sidra's Integration Hub (IH)¶
1. Enable Sidra's DSU Integration Hub feature¶
Every Sidra's DSU has a library variable group in Azure DevOps which naming will follow the next convention: {environment}.{projectName}.{dsuName}; For example: Dev.Sidra.DSU
In this variable group we will find the different settings that will be take into account when creating and setting up the DSU on the deployment. In order to enable the DSU's Integration Hub feature the variable DeployIntegrationHub must be $true. After setting up this variable value to $true, in the following deployment the feature it's going to be enabled.
At the deployment when the variable DeployIntegrationHub is detected as $true, an additional Azure resource of type Microsoft.ServiceBus/Namespaces is going to be deployed. At Sidra the -sbu suffix is used for these resources to be quickly identified,
2. Server-side setting up¶
Once the Azure Service Bus namespace resource is deployed in our Sidra's DSU installation, we will need to set up the resource.
Sidra has in its Core API a controller called TopicController. This controller allows end-users to communicate with Azure to perform all the Topics setup actions needed to work with Integration Hub.
2.1 Topic creation¶
To be able to publish messages in the Azure Service Bus resource, we will need to have a Topic where the messages are going to be published.
Sidra helps in the creation of the Azure Service Bus Topic by consuming the following endpoint:
Documentation of this endpoint can be found here.
2.2 Topic authorization¶
To be able to perform different actions on the Topic, we will need to set up a Shared Access Authorization (SAS) Policy.
Sidra helps in the creation of the Azure Service Bus Topic's SAS policy by consuming the following endpoint:
Documentation of this endpoint can be found here.
2.3 Subscription creation¶
To be able to consume the published messages, we will need to have a subscription for the Topic.
Sidra helps in the creation of the Azure Service Bus subscription by consuming the following endpoint:
[POST] api/topics/{idDataStorageUnit:int:min(1)}/{topicKeyName}/subscriptions?subscriptionKeyName={subscriptionKeyName}
Documentation of this endpoint can be found here.
3. Client-side set up¶
Once the server-side it's already set up, thanks to the Sidra's Integration Hub SDK we can easily take advantage of DSU's Integration Hub feature.
The Sidra.IntegrationHub.Client package can be used on .NET applications to easily Publish and Consume events from Integration Hub.
The package contains two Service Collection extensions that can be used to register a Publisher and a Consumer so it can be resolved by the Dependency Injection.
The package will get a SAS token from the API automatically and will take care of communication with the Service Bus as well. An example of each one is shown below.
3.1 Publish example project¶
A basic example of the publisher could be a .NET App with the following content:
using Microsoft.Extensions.DependencyInjection;
using Sidra.IntegrationHub.Client.Abstractions;
using Sidra.IntegrationHub.Client.IoCC;
using Sidra.IntegrationHub.Client.IoCC.Options;
using Sidra.IntegrationHub.Client.Sample.Common;
class Program
{
static async Task Main(string[] args)
{
await Console.Out.WriteLineAsync("Starting event publisher..");
var serviceProvider =
new ServiceCollection()
.RegisterEventPublisher(
sp =>
{
var serviceBusOptions =
new IntegrationHubPublisherOptions
{
TopicName = Constants.Consumer.TopicName,
PolicyName = Constants.Consumer.PolicyName,
TokenProviderUri = new Uri(Constants.Consumer.TokenProviderEndpoint),
ClientId = Constants.Consumer.ClientId,
ClientSecret = Constants.Consumer.Secret,
Scope = Constants.Consumer.Scope,
IntegrationHubApiEndpoint = new Uri(Constants.Consumer.IntegrationHubApiEndpoint),
IdDataStorageUnit = Constants.Consumer.DefaultDsu
};
return serviceBusOptions;
})
.BuildServiceProvider();
var eventBus = serviceProvider.GetService<IEventBus>();
var iterations = 1;
for (var i = 0; i < iterations; i++)
{
await Console.Out.WriteLineAsync("Publishing event one..");
await eventBus.Publish(new EventOne(Guid.NewGuid(), "One", DateTime.UtcNow));
await Console.Out.WriteLineAsync("Publishing event two..");
await eventBus.Publish(new EventTwo(Guid.NewGuid(), "Two", DateTime.UtcNow));
await Console.Out.WriteLineAsync("Publishing event three..");
await eventBus.Publish(new EventThree(Guid.NewGuid(), "Three", DateTime.UtcNow));
await Console.Out.WriteLineAsync("Publishing event unknown..");
await eventBus.Publish(new EventUnknown(Guid.NewGuid(), "Unknown", DateTime.UtcNow));
}
await Console.Out.WriteLineAsync("Press enter to end publisher.");
await Console.In.ReadLineAsync();
}
}
3.1.1 Publisher set up options example¶
In order to set up properly the publisher we will have to take care of the IntegrationHubPublisherOptions object when it's being declared.
Here it is an example of what the content of this setting up should it be:
var serviceBusOptions =
new IntegrationHubPublisherOptions
{
TopicName = "Test-TopicName", // Name of the existing Topic where to publish the message
PolicyName = "Test-allClaims", // Name of the existing policy name (Must have 'Send' policy at least, to be able to publish the message)
TokenProviderUri = new Uri("https://sidra-test-identityserver.azurewebsites.net/connect/token"), // Identity provider (Identity Server in this case) token endpoint where to request the user's token
ClientId = "sidraWebClient", // Identity provider's client identifier. (Client which scope it's to request the Sidra Web)
ClientSecret = "9?ARB0%^ssH:kL_", // Identity provider client's password credential
Scope = "sidra.api", // Identity provider's client's scope
IntegrationHubApiEndpoint = new Uri("https://sidra-core-test-wst-api.azurewebsites.net") // URI of the Sidra's Core API
};
3.2 Consumer example project¶
A basic example of the consumer could be a .NET App with the following content:
using Microsoft.Extensions.DependencyInjection;
using Sidra.IntegrationHub.Client.Contracts.Managers;
using Sidra.IntegrationHub.Client.IoCC;
using Sidra.IntegrationHub.Client.IoCC.Options;
using Sidra.IntegrationHub.Client.Sample.Common;
using Sidra.IntegrationHub.Client.Sample.EventConsumer;
using System.Reflection;
class Program
{
static async Task Main(string[] args)
{
await Console.Out.WriteLineAsync("Starting event consumer..");
var serviceProviderConsumerOne =
new ServiceCollection()
.RegisterEventConsumer(
sp =>
{
var serviceBusOptions =
new IntegrationHubConsumerOptions
{
TopicName = Constants.Consumer.TopicName,
PolicyName = Constants.Consumer.PolicyName,
SubscriptionName = Constants.Consumer.SubscriptionOne,
TokenProviderUri = new Uri(Constants.Consumer.TokenProviderEndpoint),
ClientId = Constants.Consumer.ClientId,
ClientSecret = Constants.Consumer.Secret,
Scope = Constants.Consumer.Scope,
IntegrationHubApiEndpoint = new Uri(Constants.Consumer.IntegrationHubApiEndpoint),
IdDataStorageUnit = Constants.Consumer.DefaultDsu
};
return serviceBusOptions;
},
typeof(EventOneHandler).GetTypeInfo().Assembly)
.BuildServiceProvider();
await Console.Out.WriteLineAsync("Starting consumer one..");
var eventConsumerOneManager = serviceProviderConsumerOne.GetService<IEventConsumerBusManager>();
await eventConsumerOneManager.Start();
await Console.Out.WriteLineAsync("Press enter to end consumers.");
await Console.In.ReadLineAsync();
await eventConsumerOneManager.Stop();
}
}
3.2.1 Consumer set up options example¶
In order to set up properly the consumer we will have to take care of the IntegrationHubConsumerOptions object when it's being declared.
Here it is an example of what the content of this setting up should it be:
var serviceBusOptions =
new IntegrationHubConsumerOptions
{
TopicName = "Test-TopicName", // Name of the existing Topic where to publish the message
PolicyName = "Test-allClaims", // Name of the existing policy name (Must have 'Send' policy at least, to be able to publish the message)
SubscriptionName = "Test-Subscription" /// Name of the existing Topic's subscription to listen the messages
TokenProviderUri = new Uri("https://sidra-test-identityserver.azurewebsites.net/connect/token"), // Identity provider (Identity Server in this case) token endpoint where to request the user's token
ClientId = "sidraWebClient", // Identity provider's client identifier. (Client which scope it's to request the Sidra Web)
ClientSecret = "9?ARB0%^ssH:kL_", // Identity provider client's password credential
Scope = "sidra.api", // Identity provider's client's scope
IntegrationHubApiEndpoint = new Uri("https://sidra-core-test-wst-api.azurewebsites.net") // URI of the Sidra's Core API
};