Azure/device-telemetry-dotnet

Name: device-telemetry-dotnet

Owner: Microsoft Azure

Description: Device telemetry implementation in .NET for PCS

Created: 2017-06-20 20:51:02.0

Updated: 2018-03-30 19:46:32.0

Pushed: 2018-03-30 23:17:56.0

Homepage: null

Size: 179

Language: C#

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Device Telemetry Overview

This service provides a RESTful endpoint for read access to device telemetry, full CRUD for rules, and read/write for alarms from storage.

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

• Gets a list of telemetry messages
• Gets a list of alarms
• Gets a single alarm
• Modifies alarm status
• Create/Read/Update/Delete Rules

Documentation

• View the API documentation in the Wiki.

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.

• Cosmos DB

2. Setup Dependencies

This service depends on the following repository.

1. Storage Adapter Microservice

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_TELEMETRY_DOCUMENTDB_CONNSTRING = {your Azure Cosmos DB connection string}
• PCS_STORAGEADAPTER_WEBSERVICE_URL = http://localhost:9022/v1

Running the service with Visual Studio

1. Make sure the Prerequisites are set up.
2. Install any edition of Visual Studio 2017 or Visual Studio for Mac. When installing check “.NET Core” workload. If you already have Visual Studio installed, then ensure you have .NET Core Tools for Visual Studio 2017 installed (Windows only).
3. Open the solution in Visual Studio
4. Edit the WebService project properties by right clicking on the Webservice project > Properties > Debug. Add following required environment variables to the Debug settings. In Windows you can also set these in your system.
5. PCS_TELEMETRY_DOCUMENTDB_CONNSTRING = {your Azure Cosmos DB connection string}
6. PCS_STORAGEADAPTER_WEBSERVICE_URL = http://localhost:9022/v1
7. In Visual Studio, start the WebService project
8. 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_TELEMETRY_DOCUMENTDB_CONNSTRING = {your Azure Cosmos DB connection string}
   2. PCS_STORAGEADAPTER_WEBSERVICE_URL = http://localhost:9022/v1
3. Use the scripts in the scripts folder for many frequent tasks:
4. build: compile all the projects and run the tests.
5. compile: compile all the projects.
6. 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 managing Ruels, Alarms, and Messages
• WebService.Test.csproj - Unit tests for web services functionality
• Services.csproj - C# assembly containining business logic for interacting with storage and the Storage Adapter microservice
• 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. The application also supports references to environment variables, which is used to import credentials and networking details.

The configuration files in the repository reference some environment variables that need to be created at least once. Depending on your OS and the IDE, there are several ways to manage environment variables:

• Windows: the variables can be set in the system as a one time only task. The env-vars-setup.cmd script included needs to be prepared and executed just once. The settings will persist across terminal sessions and reboots.
• Visual Studio: the variables can be set in the project settings for WebService under Project Properties -> Configuration Properties -> Environment
• For Linux and OSX environments, the env-vars-setup script needs to be executed every time a new console is opened. Depending on the OS and terminal, there are ways to persist values globally, for more information these pages should help:
• 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

Contributing to the solution

Please follow our contribution guidelines. We love PRs too.

Feedback

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

License

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