Config Service Overview
This service handles communication with the Storage Adapter microservice to complete tasks.
The microservice provides a RESTful endpoint to make CRUD operations for "devicegroups", "solution-settings", and "user-settings". The data will be stored by the Storage Adapter microservice.
- Create or update device groups
- Get all or a single device group
- Get or upload logo
- Get or set overall solution settings
- Get or set individual user settings
- View the API documentation in the Wiki
How to Use
Running the Service with Docker
Running the Service Locally
1. Deploy Azure Services
This service has a dependency on the following Azure resources. Follow the instructions for Deploy the Azure services.
- Cosmos DB
- Iot Hub
- Maps (optional)
2. Setup Dependencies
This service depends on the following repositories. Run those services from the instructions in their READMEs in the following order.
- Storage Adapter Dotnet Microservice
- Telemetry Dotnet Microservice
- Device Simulation Dotnet 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_STORAGEADAPTER_WEBSERVICE_URL- the url for the Storage Adapter Webservice used for key value storage
PCS_DEVICESIMULATION_WEBSERVICE_URL- the url for the Device Simulation Webservice used for key value storage
PCS_TELEMETRY_WEBSERVICE_URL- the url for the Telemetry Webservice used for key value storage
PCS_AZUREMAPS_KEY- the Azure Maps API Key. This can be set to "static" if you do not have one.
Running the service with Visual Studio or VS Code
- Make sure the Prerequisites are set up.
- Install .NET Core 2.x
- Install any recent edition of Visual Studio (Windows/MacOS) or Visual Studio Code (Windows/MacOS/Linux).
- Open the solution in Visual Studio or VS Code.
- Define the following environment variables. See Configuration and Environment variables for detailed information for setting these for your enviroment.
- Start the WebService project (e.g. press F5).
- Use an HTTP client such as Postman, to exercise the RESTful API.
Running the service from the command line
- Make sure the Prerequisites are set up.
- Set the following environment variables in your system. More information on environment variables here.
- 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.
This microservice contains the following projects:
- WebService.csproj - C# web service exposing REST interface for config functionality
- WebService.Test.csproj - Unit tests for web services functionality
- Services.csproj - C# assembly containining business logic for interacting with storage microserivce, telemetry microservice and device simulation 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
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 accessed via ASP.NET Core configuration adapters, and stored in appsettings.ini. The INI format allows to store values in a readable format, with comments.
The configuration also supports references to environment variables, e.g. to import credentials and network details. Environment variables are not mandatory though, you can for example edit appsettings.ini and write credentials directly in the file. Just be careful not sharing the changes, e.g. sending a Pull Request or checking in the changes in git.
The configuration file in the repository references some environment variables that need to be defined. Depending on the OS and the IDE used, there are several ways to manage environment variables.
- If you're using Visual Studio (Windows/MacOS), 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.
- Visual Studio Code (Windows/MacOS/Linux) loads the environment variables from .vscode/launch.json
- When running the service with Docker or from the command line, the
application will inherit environment variables values from the system.
- This page describes how to setup env vars in Windows. We suggest to edit and execute once the env-vars-setup.cmd script included in the repository. The settings will persist across terminal sessions and reboots.
- For Linux and MacOS, we suggest to edit and execute env-vars-setup each time, before starting the service. Depending on OS and terminal, there are ways to persist values globally, for more information these pages should help:
Contributing to the solution
Please follow our contribution guildelines and code style conventions.
Please enter issues, bugs, or suggestions as GitHub Issues.
Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License.