remote-monitoring-services-dotnet/iothub-manager

IoTHub Manager Overview

This service manages most of Azure IoT Hub interactions, such as creating and managing IoT devices, device twins, invoking methods, managing IoT credentials, etc. This service is also used to run queries to retrieve devices belonging to a particular group (defined by the user).

The microservice provides a RESTful endpoint to manage devices, device twins, commands, methods and all the Azure IoT Hub features required by the Azure IoT Remote Monitoring project.

Why?

This microservice was built as part of the Azure IoT Remote Monitoring project to provide a generic implementation for an end-to-end IoT solution. More information here.

Features

• Device creation in IoT Hub
• Read for all devices
• Read for a single device
• Query for set of devices
• Update devices
• Delete devices
• Schedule jobs
  • Execute methods
  • Update the device twin
• Get a list of jobs
• Get a single job

Documentation

• View the API documentation in the Wiki
• Contributing and Development setup
• Development setup, scripts and tools

How to use

Running the service with Docker

You can run the microservice and its dependencies using Docker with the instructions here.

Running the service locally

Prerequisites

1. Deploy Azure Services

This service has a dependency on the following Azure resources. Follow the instructions for Deploy the Azure services to deploy the required resources.

• Azure IoT Hub

2. Setup Dependencies

This service depends on the Storage Adapter microservice. Run the Storage Adapter microservice using the the instructions in the Storage Adapter service README.md.

Note: you can also use a deployed endpoint with Authentication disabled (e.g. https://{your-resource-group}.azurewebsites.net/storageadapter/v1)

3. Environment variables required to run the service

In order to run the service, some environment variables need to be created at least once. See specific instructions for IDE or command line setup below for more information. More information on environment variables here.

• PCS_AAD_APPID = { Azure service principal id }
• PCS_AAD_APPSECRET = { Azure service principal secret }
• PCS_KEYVAULT_NAME = { Name of Key Vault resource that stores settings and configuration }

Configuration values used from Key Vault

Some of the configuration needed by the microservice is stored in an instance of Key Vault that was created on initial deployment. The iothub-manager microservice uses:

• aadAppId = Azure Active Directory application / service principal id.
• authIssuer = Identifies the security token service (STS) i.e. https://sts.windows.net/tenantId/
• authRequired = Whether or not authentication is needed for calls to microservices i.e. from the web ui or postman
• authWebServiceUrl = Endpoint for the remote monitoring auth microservice
• corsWhitelist = Specifies where requests are allowed from "{ 'origins': ['*'], 'methods': ['*'], 'headers': ['*'] }" to allow everything. Empty to disable CORS
• storageAdapterWebServiceUrl = Endpoint for storage adapter microservice
• subscriptionId = GUID that uniquely identifies your subscription to use Azure services

Running the service with Visual Studio or VS Code

1. Make sure the Prerequisites are set up.
2. Install .NET Core 2.x
3. Install any recent edition of Visual Studio (Windows/MacOS) or Visual Studio Code (Windows/MacOS/Linux).
   • If you already have Visual Studio installed, then ensure you have .NET Core Tools for Visual Studio 2017 installed (Windows only).
   • If you already have VS Code installed, then ensure you have the C# for Visual Studio Code (powered by OmniSharp) extension installed.
4. Open the solution in Visual Studio or VS Code
5. Define the following environment variables. See Configuration and Environment variables for detailed information for setting these for your enviroment.
   1. PCS_AAD_APPID = { Azure service principal id }
   2. PCS_AAD_APPSECRET = { Azure service principal secret }
   3. PCS_KEYVAULT_NAME = { Name of Key Vault resource that stores settings and configuration }
6. Start the WebService project (e.g. press F5).
7. Using an HTTP client like Postman, use the RESTful API to test out the service.

Running the service from the command line

1. Make sure the Prerequisites are set up.
2. Set the following environment variables in your system. More information on environment variables here.
   1. PCS_AAD_APPID = { Azure service principal id }
   2. PCS_AAD_APPSECRET = { Azure service principal secret }
   3. PCS_KEYVAULT_NAME = { Name of Key Vault resource that stores settings and configuration }
3. Use the scripts in the scripts folder for many frequent tasks:

• build: compile all the projects and run the tests.
• compile: compile all the projects.
• run: compile the projects and run the service. This will prompt for elevated privileges in Windows to run the web service.

Project Structure

This microservice contains the following projects:

• WebService.csproj - C# web service exposing REST interface for storage functionality
• WebService.Test.csproj - Unit tests for web services functionality
• Services.csproj - C# assembly containining business logic for interacting with Azure Cosmos account with type SQL
• Services.Test.csproj - Unit tests for services functionality
• Solution/scripts - Contains build scripts, docker container creation scripts, and scripts for running the microservice from the command line

Updating the Docker image

The scripts folder includes a docker subfolder with the files required to package the service into a Docker image:

• Dockerfile: docker images specifications
• build: build a Docker container and store the image in the local registry
• run: run the Docker container from the image stored in the local registry
• content: a folder with files copied into the image, including the entry point script

Configuration and Environment variables

The service configuration is stored using ASP.NET Core configuration adapters, in appsettings.ini. The INI format allows to store values in a readable format, with comments.

Configuration in appsettings.ini are typically set in 3 different ways:

1. Environment variables as is the case with ${PCS_AAD_APPID}. This is typically only done with the 3 variables described above as these are needed to access Key Vault. More details about setting environment variables are located below.
2. Key Vault: A number of the settings in this file will be blank as they are expecting to get their value from a Key Vault secret of the same name.
3. Direct Value: For some values that aren't typically changed or for local development you can set the value directly in the file.

Depending on the OS and the IDE used, there are several ways to manage environment variables.

1. If you're using Visual Studio or Visual Studio for Mac, the environment variables are loaded from the project settings. Right click on WebService, and select Options/Properties, and find the section with the list of env vars. See WebService/Properties/launchSettings.json.
2. Visual Studio Code loads the environment variables from .vscode/launch.json
3. When running the service with Docker or from the command line, the application will inherit environment variables values from the system.
   • Depending on OS and terminal, there are different ways to persist values globally, for more information these pages should help:
     • https://superuser.com/questions/949560/
     • https://stackoverflow.com/questions/13046624/how-to-permanently-export-a-variable-in-linux
     • https://stackoverflow.com/questions/135688/setting-environment-variables-in-os-x
     • https://help.ubuntu.com/community/EnvironmentVariables
4. IntelliJ Rider: env. vars can be set in each Run Configuration, similarly to IntelliJ IDEA (https://www.jetbrains.com/help/idea/run-debug-configuration-application.html)

Contributing to the solution

Please follow our contribution guidelines. We love PRs too.

Feedback

Please enter issues, bugs, or suggestions as GitHub Issues here.

License

Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License.