Deploying Azure IoT Hub Connectors

On-premises deployments can use Azure IoT Hub to connect data sources to real-time digital twin instances. Please see the topic Azure IoT Hub for detailed information about connecting to Azure IoT Hub and routing messages from data sources to the correct real-time digital twin models and instances.

This section describes how to use .NET APIs to deploy an Azure IoT Core connector to an on-premises deployment of ScaleOut StreamServer instead of to the ScaleOut Digital Twins™ service.

Note

Support for launching an Azure IoT Hub connector is currently only available in .NET. Messages can be sent into Azure IoT Hub using any supported library, however the connector which receives those messages and processes them for their respective real-time digital twin instances is launched as a .NET Framework-based process.

Prerequisites

Before deploying an Azure IoT Hub connector, first define and deploy a real-time digital twin model.

As a prerequisite, you should have Visual Studio and .NET Framework 4.7.2 or newer installed. To deploy and manage an Azure IoT Hub Connector, you should install the ScaleOut.AzureIoT.Client NuGet package in your Visual Studio project.

Managing an Azure IoT Hub connector

To deploy an Azure IoT Hub connector, your client application needs to call the EventListenerManager.StartAzureIoTHubConnector static method.

You can also temporary disable message processing by calling the EventListenerManager.DisableAzureIoTHubConnector static method.

Example

The following code snippet illustrates how to start, stop, enable and disable an Azure IoT Hub connector:

using Scaleout.AzureIoT.Client;
using Scaleout.Streaming.DigitalTwin.Common;

namespace ScaleOut.Streaming.Documentation.Samples
{
    class AzureConnectorDeploymentProgram
    {
        // Azure-specific configuration -- retrieve these details from the Azure Portal
        public const string _eventHubName             = "MyHub";
        public const string _eventHubEventsEndpoint   = "Endpoint=sb://iothub-ns-myhub-123456-7890abcdef.servicebus.windows.net/;SharedAccessKeyName=iothubowner;SharedAccessKey=key_value";
        public const string _storageConnectionString  = "DefaultEndpointsProtocol=https;AccountName=XYZ;AccountKey=key_value;EndpointSuffix=core.windows.net";
        public const string _eventHubConnectionString = "HostName=myhub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=key_value";

        static void Main(string[] args)
        {
            // Start the ScaleOut Azure IoT Hub Connector
            // (the code below assumes you have created a consumer group called
            // BridgeToScaleOut in your Azure IoT Hub called MyHub here):
            EventListenerManager.StartAzureIoTHubConnector(
                        connectorId             : "MyAzureIoTHubConnector",
                        eventHubName            : _eventHubName,
                        eventHubConnectionString: _eventHubConnectionString,
                        eventHubEventsEndpoint  : _eventHubEventsEndpoint,
                        storageConnectionString : _storageConnectionString,
                                    maxBatchSize: 64,
                        scaleoutConnectionString: "",
                        initialState            : InitialConnectorState.Enabled,
                        consumerGroupName       : "BridgeToScaleOut");

            // Disable the connector:
            EventListenerManager.DisableAzureIoTHubConnector(connectorId: "MyAzureIoTHubConnector");

            // Enable the connector again:
            EventListenerManager.EnableAzureIoTHubConnector(connectorId: "MyAzureIoTHubConnector");

            // Finally, stop the connector:
            EventListenerManager.StopAzureIoTHubConnector(connectorId: "MyAzureIoTHubConnector");
        }
    }
}