Name: device-telemetry-dotnet
Owner: ms-iot
Description: Device telemetry implementation in .NET for PCS
Forked from: Azure/device-telemetry-dotnet
Created: 2017-12-16 00:42:03.0
Updated: 2018-04-30 19:20:09.0
Pushed: 2017-12-16 00:45:40.0
Homepage:
null
Size: 153
Language: C#
GitHub Committers
User | Most Recent Commit | # Commits |
Other Committers
User | Email | Most Recent Commit | # Commits |
README
Device Telemetry Overview
This service offers read access to device telemetry, full CRUD for rules, and read/write for
alarms from storage for the client via a RESTful endpoint.
Features the microservice offers:
- Gets a list of telemetry messages for specific parameters
- Gets a list of alarms for specific parameters
- Gets a single alarm
- Modifies alarm status
- Create/Read/Update/Delete Rules
- Create Rules
- Gets a list of rules for specific parameters
- Gets a single rule
- Modify existing rule
- Delete existing rule
Dependencies
- DocumentDB Storage
- Storage Adapter Webservice
How to use the microservice
Quickstart - Running the service with Docker
- Create an instance of Azure Document Db
- Follow the Storage quickstart instructions
for setting up the Storage Adapter microservice storage.
- Find your DocumentDb connection string. See
See the tip here if you
need help finding it.
- Store the “Document Db Connection string” in the env-vars-setup
script, then run the script. In MacOS/Linux the environment variables
need to be set in the same session where you run Docker Compose,
every time a new session is created.
- Install Docker Compose
- Start the Telemetry service using docker compose:
cripts
ocker
er-compose up
- Use an HTTP client such as Postman, to exercise the
RESTful API
Local Setup
1. Environment Variables
Run scripts\env-vars-setup.cmd
on Windows or source scripts\env-vars-setup
on Mac/Linux to set up the environment variables needed to run the service locally.
In Windows you can also set these in your system.
If using envornemnt variables, this service requires the following environment
variables to be set:
PCS_TELEMETRY_DOCUMENTDB_CONNSTRING
= {your Azure Document Db connection string}
PCS_STORAGEADAPTER_WEBSERVICE_URL
= http://localhost:9022/v1
Running the service with Visual Studio
- 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).
- Create an instance of Azure Document Db
- Follow the Storage quickstart instructions
for setting up and running the Storage Adapter microservice.
- Open the solution in Visual Studio
- Edit the WebService project properties, and
define the following required environment variables. In Windows
you can also set these in your system.
PCS_TELEMETRY_DOCUMENTDB_CONNSTRING
= {your Azure Document Db connection string}
PCS_STORAGEADAPTER_WEBSERVICE_URL
= http://localhost:9022/v1
- In Visual Studio, start the WebService project
- Using an HTTP client like Postman,
use the RESTful API
Project Structure
The solution contains the following projects and folders:
- Code for the application is in app/com.microsoft.azure.iotsolutions.telemetry/
- WebService - ASP.NET Web API exposing a RESTful API for for managing Ruels,
Alarms, and Messages
- Services - Library containing common business logic for interacting with
storage and the StorageAdapter
- Tests are in the test folder
- WebService - Tests for web services functionality
- Service - Tests for services functionality
- Scripts - a folder containing scripts from the command line console,
to build and run the solution, and other frequent tasks.
- Routes - defines the URL mapping to web service classes
Build and Run from the command line
The scripts folder contains scripts 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.
Building a customized Docker image
The scripts
folder includes a docker subfolder with the
scripts required to package the service into a Docker image:
Dockerfile
: Docker image specifications
build
: build a Docker image 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
You can also start Device Telemetry and its dependencies in one simple step,
using Docker Compose with the
docker-compose.yml file in the project:
cripts
ocker
er-compose up
The Docker compose configuration requires the Storage and StorageAdapter web
service URL environment variables, described previously.
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
Other resources
Contributing to the solution
Please follow our contribution guidelines. We love PRs too.
Troubleshooting
{TODO}
Feedback
Please enter issues, bugs, or suggestions as GitHub Issues here: https://github.com/Azure/device-telemetry-dotnet/issues.