Microsoft Azure IoT SDK for .NET
This repository contains the following:
- Microsoft Azure IoT Hub device SDK for C# to connect client devices to Azure IoT Hub with .NET.
- Microsoft Azure IoT Hub service SDK for C# to manage your IoT Hub service instance from a back-end .NET application.
- Microsoft Azure Provisioning device SDK for C# to provision devices to Azure IoT Hub with .NET.
- Microsoft Azure Provisioning service SDK for C# to manage your Provisioning service instance from a back-end .NET application.
Due to security considerations, build logs are not publicly available.
Recommended NuGet packages
The API reference documentation for .NET SDK is here.
- Have a feature request for SDKs? Please post it on User Voice to help us prioritize.
- Have a technical question? Ask on Stack Overflow with tag “azure-iot-hub”.
- Need Support? Every customer with an active Azure subscription has access to support with guaranteed response time. Consider submitting a ticket and get assistance from Microsoft support team.
- Found a bug? Please help us fix it by thoroughly documenting it and filing an issue on GitHub (C, Java, .NET, Node.js, Python).
Developing applications for Azure IoT
Visit Azure IoT Dev Center to learn more about developing applications for Azure IoT.
Most of our samples are available at Azure IoT Samples for C#.
If you are looking for a good device sample to get started with, please see the device reconnection sample.
It shows how to connect a device, handle disconnect events, cases to handle when making calls, and when to re-initialize the
Contribute to the Azure IoT C# SDK
If you would like to build or change the SDK source code, please follow the devguide.
OS platforms and hardware compatibility
The IoT Hub device SDK for .NET can be used with a broad range of OS platforms and devices, mainly modern versions Windows and Linux.
The NuGet packages provide support for the following .NET flavors:
- .NET Standard 2.1
- .NET Standard 2.0
- .NET Framework 4.7.2 (IoT Hub SDKs only)
- .NET Framework 4.5.1 (IoT Hub SDKs only)
For details on .NET support see the .NET Standard documentation. For details on OS support see the following resources:
- .NET Core Runtime ID Catalog
- .NET Framework System Requirements
- Configure TLS Protocol Version and Ciphers
Key features and roadmap
IoT Hub Device SDK
|Authentication||Connect your device to IoT Hub securely with supported authentication, including private key, SASToken, X-509 Self Signed and X-509 CA Signed. *IoT Hub only supports X-509 CA Signed over AMQP and MQTT at the moment. X509-CA authentication over websocket and HTTPS are not supported.|
|Send device-to-cloud message||Send device-to-cloud messages (max 256KB) to IoT Hub with the option to add application properties and system properties, and batch send. *IoT Hub only supports batch send over AMQP and HTTPS at the moment. The MQTT implementation loops over the batch and sends each message individually.|
|Receive cloud-to-device messages||Receive cloud-to-device messages and read associated application and system properties from IoT Hub, with the option to complete/reject/abandon C2D messages. *IoT Hub does not support the option to reject/abandon C2D messages over MQTT at the moment.|
|Device Twins||IoT Hub persists a device twin for each device that you connect to IoT Hub. The device can perform operations like get twin tags, subscribe to desired properties. *Send reported properties version and desired properties version are in progress.|
|Direct Methods||IoT Hub gives you the ability to invoke direct methods on devices from the cloud. The SDK supports handler for method specific amd generic operation.|
|Upload file to Blob||The user can use the device client to retrieve a SAS URI from IoT Hub (to use for file uploads), upload to Azure Storage blob using IoT Hub provided credentials (using a supported client library), and then use the device client to notify IoT Hub that a file upload has completed. File upload requires HTTPS connection, but can be initiated from client using any protocol for other operations.|
|Connection Status and Error reporting||Error reporting for IoT Hub supported error code.|
|Retry policies||Retry policy for unsuccessful device-to-cloud messages have three options: no try, exponential backoff with jitter (default) and custom.|
|Devices multiplexing over single connection|
|Connection Pooling - Specifying number of connections|
IoT Hub Service SDK
|Features||Support||Transport protocol used underneath||Description|
|Identity registry (CRUD)||HTTP||Use your backend app to perform CRUD operation for individual device or in bulk.|
|Cloud-to-device messaging||AMQP||Use your backend app to send cloud-to-device messages in AMQP and AMQP-WS, and set up cloud-to-device message receivers.|
|Direct Methods operations||HTTP||Use your backend app to invoke direct method on device.|
|Device Twins operations||HTTP||Use your backend app to perform twin operations.|
|Query||HTTP||Use your backend app to perform query for information.|
|Jobs||HTTP||Use your backend app to perform job operation.|
|File Upload||AMQP||Set up your backend app to receive file upload notifications.|
|Digital Twin Client||HTTP||Set up your backend app to perform operations on plug and play devices.|
|IoT Hub Statistics||HTTP||Get IoT Hub identity registry statistics; such as total device count for device statistics, and connected device count for service statistics.|
Provisioning Device SDK
|TPM Individual Enrollment||This SDK supports connecting your device to the Device Provisioning Service via individual enrollment using Trusted Platform Module. Please review the samples folder and this quickstart on how to create a device client. TPM over MQTT is currently not supported by the Device Provisioning Service.|
|X.509 Individual Enrollment||This SDK supports connecting your device to the Device Provisioning Service via individual enrollment using X.509 root certificate. Please review the samples and this quickstart folder on how to create a device client.|
|X.509 Enrollment Group||This SDK supports connecting your device to the Device Provisioning Service via individual enrollment using X.509 leaf certificate. Please review the samples folder on how to create a device client.|
Note * WebSocket support for MQTT/AMQP is limited to .NET Framework 4.x.
Provisioniong Service SDK
|CRUD Operation with TPM Individual Enrollment||Programmatically manage device enrollment using TPM with the service SDK. Please visit the samples folder to learn more about this feature.|
|Bulk CRUD Operation with TPM Individual Enrollment||Programmatically bulk manage device enrollment using TPM with the service SDK. Please visit the samples folder to learn more about this feature.|
|CRUD Operation with X.509 Individual Enrollment||Programmatically manage device enrollment using X.509 individual enrollment with the service SDK. Please visit the samples folder to learn more about this feature.|
|CRUD Operation with X.509 Group Enrollment||Programmatically manage device enrollment using X.509 group enrollment with the service SDK. Please visit the samples folder to learn more about this feature.|
|Query enrollments||Programmatically query registration states with the service SDK. Please visit the samples folder to learn more about this feature.|
- Azure IoT Hub documentation
- Set up IoT Hub describes how to configure your Azure IoT Hub service.
- Manage IoT Hub describes how to provision devices in your Azure IoT Hub service.
- Azure Certified for IoT device catalog
- Set up your development environment to prepare your development environment as well as how to run the samples on Linux, Windows or other platforms.
- API reference documentation for .NET
- Get Started with IoT Hub using .NET
Device Explorer is no longer supported. A replacement tool can be found here.
Certificates - Important to know
The Azure IoT Hub certificates presented during TLS negotiation shall be always validated using the appropriate root CA certificate(s).
Always prefer using the local system's Trusted Root Certificate Authority store instead of hardcoding the certificates.
A couple of examples:
- Windows: Schannel will automatically pick up CA certificates from the store managed using
- Debian Linux: OpenSSL will automatically pick up CA certificates from the store installed using
apt install ca-certificates. Adding a certificate to the store is described here: http://manpages.ubuntu.com/manpages/precise/man8/update-ca-certificates.8.html
For additional guidance and important information about certificates, please refer to this blog post from the security team.
Long-Term Support (LTS)
The project offers a Long Term Support (LTS) version to allow users that do not need the latest features to be shielded from unwanted changes.
As of August 2020, the .NET SDK is shifting to a revised Long-Term Support strategy. The primary motivations for this change are to extend the support period and decrease the churn on LTS releases, while still maintaining a strategy that offers customers choice between new features and stability.
We now will be releasing a new LTS branch yearly, and each LTS release will be supported for 3 years - 1 year of active maintenance with bugfixes, and 2 years of extended support for security fixes.
LTS branches receive all bug fixes that fall in one of these categories:
- security bugfixes
- critical bugfixes (crashes, memory leaks, etc.)
No new features or improvements will be picked up in an LTS branch.
LTS branches are named lts_yyyy_mm, where mm and yyyy are the month and year when the branch was created. An example of such a branch is lts_2018_01.
Below is a table showing the mapping of the LTS branches to the packages released.
|Release||Github Branch||LTS Status||LTS Start Date||Maintenance End Date||Removed Date|
- 1 All scheduled dates are subject to change by the Azure IoT SDK team.
Planned release schedule
Microsoft collects performance and usage information which may be used to provide and improve Microsoft products and services and enhance your experience. To learn more, review the privacy statement.