Microsoft.Azure.Devices.Client 2.0.0-preview005

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
This is a prerelease version of Microsoft.Azure.Devices.Client.
The owner has unlisted this package. This could mean that the package is deprecated, has security vulnerabilities or shouldn't be used anymore.
dotnet add package Microsoft.Azure.Devices.Client --version 2.0.0-preview005
NuGet\Install-Package Microsoft.Azure.Devices.Client -Version 2.0.0-preview005
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Microsoft.Azure.Devices.Client" Version="2.0.0-preview005" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Microsoft.Azure.Devices.Client --version 2.0.0-preview005
#r "nuget: Microsoft.Azure.Devices.Client, 2.0.0-preview005"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Microsoft.Azure.Devices.Client as a Cake Addin
#addin nuget:?package=Microsoft.Azure.Devices.Client&version=2.0.0-preview005&prerelease

// Install Microsoft.Azure.Devices.Client as a Cake Tool
#tool nuget:?package=Microsoft.Azure.Devices.Client&version=2.0.0-preview005&prerelease

Microsoft Azure IoT SDK for .NET

V2 clients release notice

The 2.0.0-preview001 release has been published for each package in this library. These packages simplify usage and handling of our clients, and we highly encourage you to try out these packages and share your feedback. Once we promote these changes to main in the future and release the 2.x.x packages publicly, all future features will be brought only to this new major version.

If you need any help migrating your code to try out the new 2.X.X clients, please see this migration guide.

Contents

This repository contains the following:

  • Microsoft Azure IoT Hub device SDK for .NET to connect client devices to Azure IoT Hub with .NET.
  • Microsoft Azure IoT Hub service SDK for .NET to manage your IoT Hub service instance from a back-end .NET application.
  • Microsoft Azure Provisioning device SDK for .NET to provision devices to Azure IoT Hub with .NET.
  • Microsoft Azure Provisioning service SDK for .NET to manage your Provisioning service instance from a back-end .NET application.

Critical Upcoming Change Notice

All Azure IoT SDK users are advised to be aware of upcoming TLS certificate changes for Azure IoT Hub and Device Provisioning Service that will impact the SDK's ability to connect to these services. In October 2022, both services will migrate from the current Baltimore CyberTrust CA Root to the DigiCert Global G2 CA root. There will be a transition period beforehand where your IoT devices must have both the Baltimore and Digicert public certificates installed in their certificate store in order to prevent connectivity issues.

Devices with only the Baltimore public certificate installed will lose the ability to connect to Azure IoT hub and Device Provisioning Service in October 2022.

To prepare for this change, make sure your device's certificate store has both of these public certificates installed.

For a more in depth explanation as to why the IoT services are doing this, please see this article.

Package Name Release Version
Microsoft.Azure.Devices.Client NuGet
Microsoft.Azure.Devices NuGet
Microsoft.Azure.Devices.Provisioning.Client NuGet
Microsoft.Azure.Devices.Provisioning.Service NuGet

Note:

  1. In addition to stable builds we also release pre-release builds that contain preview features. You can find details about the preview features released by looking at the release notes. It is not recommended to take dependency on preview NuGets for production applications as breaking changes can be introduced in preview packages.

  2. Device streaming feature is not being included in our newer preview releases as there is no active development going on in the service. For more details on the feature, see here.

    This feature has not been included in any preview release after 2020-10-14. However, the feature is still available under previews/deviceStreaming branch.

    The latest preview NuGet versions that contain the device streaming feature are:
    Microsoft.Azure.Devices.Client - 1.32.0-preview-001
    Microsoft.Azure.Devices - 1.28.0-preview-001

  3. Stable and preview NuGet versions are not interdependent; eg. for NuGet packages versioned 1.25.0 (stable release) and 1.25.0-preview-001 (preview release), there is no guarantee that v1.25.0 contains the feature(s) previewed in v1.25.0-preview-001. For a list of updates shipped with each NuGet package, please refer to the release notes.

The API reference documentation for .NET SDK is here.

To find SDKs in other languages for Azure IoT, please refer to the azure-iot-sdks repository. For IoT Hub Management SDK in .NET, please visit azure-sdk-for-net repository.

Need support?

  • 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.

Samples

All of our samples are located in this repository. The samples live alongside the source for each client library.

Samples for each of these categories are further separated into three sub-categories (from simplest to complex):

  1. Getting Started
  2. How To
  3. Solutions

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 DeviceClient.

Contribute to the Azure IoT .NET SDK

If you would like to build or change the SDK source code, please follow the devguide.

OS platforms and hardware compatibility

For an official list of all the operating systems and .NET platforms that we support, please see this document.

Note that you can configure your TLS protocol version and ciphers by following this document.

Key features and roadmap

IoT Hub Device SDK

✔️ feature available ✖️ feature planned but not supported ➖ no support planned

Features mqtt mqtt-ws amqp amqp-ws Description
Authentication ✔️ ✔️* ✔️ ✔️* Connect your device to IoT Hub securely with supported authentication methods, including private key, shared access signature (SAS) token, X.509 self-signed, and X.509 certificate authority (CA) signed. </br> *IoT Hub only supports X.509 CA signed over AMQP and MQTT at the moment. X.509 CA authentication over web socket and HTTPS are not supported. When authenticating a device using shared access key (SAK) over MQTT, new connection will be setup as part of the SAS token refresh process; device communication will be briefly closed during refresh (for details, see device connection and messaging reliability documentation). X.509 certificate-based authentication process does not have the same refresh disruption. Also, X.509 certificate-based authentication is more secure than share access key authentication.
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. </br> *IoT Hub only supports batch send over AMQP at the moment.
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. </br> *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. </br> *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 and 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 Plug and Play ✔️ ✔️ ✔️* ✔️* IoT Plug and Play lets you build smart devices that advertise their capabilities to Azure IoT applications. IoT Plug and Play devices don't require manual configuration when a customer connects them to IoT Plug and Play-enabled applications. You can read more here. </br> *Note: AMQP support is mainly targeted for Edge-based scenarios.

IoT Hub Service SDK

✔️ feature available ✖️ feature planned but not supported ➖ no support planned

Features Support Transport protocol used underneath Client to use Description
Identity registry (CRUD) ✔️ HTTP RegistryManager Use your backend app to perform CRUD operation for individual device or in bulk.
Query ✔️ HTTP RegistryManager Use your backend app to query for information on device twins, module twins, jobs and message routing.
Import/Export jobs ✔️ HTTP RegistryManager Use your backend app to import or export device identities in bulk.
Scheduled jobs ✔️ HTTP JobsClient Use your backend app to schedule jobs to update desired properties, update tags and invoke direct methods.
Cloud-to-device messaging ✔️ AMQP ServiceClient Use your backend app to send cloud-to-device messages in AMQP and AMQP-WS, and set up notifications for cloud-to-device message delivery.
Direct Methods operations ✔️ HTTP ServiceClient Use your backend app to invoke direct method on device.
File Upload Notifications ✔️ AMQP ServiceClient Use your backend app to receive file upload notifications.
IoT Hub Statistics ✔️ HTTP ServiceClient Use your backend app to get IoT hub identity registry statistics such as total device count for device statistics, and connected device count for service statistics.
Digital Twin Operations ✔️ HTTP DigitalTwinClient or RegistryManager Use your backend app to perform operations on plug and play devices. The operations include get twins, update twins and invoke commands. DigitalTwinClient is the preferred client to use.

Provisioning Device SDK

This repository contains provisioning device client SDK for the Device Provisioning Service.

✔️ feature available ✖️ feature planned but not supported ➖ no support planned

Features mqtt mqtt-ws amqp amqp-ws Description
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

This repository contains provisioning service client SDK for the Device Provisioning Service to programmatically enroll devices.

Feature Support Description
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.

Read more

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:

Additional Information

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) releases to allow users that do not need the latest features to be shielded from unwanted changes.

LTS repo tags are to be named lts_yyyy-mm-dd, where yyyy, mm, and dd are the year, month, and day when the tag was created. An example of such a tag is lts_2021-03-18.

The lifetime of an LTS release is 12 months. During this time, LTS releases may receive maintenance bug fixes that fall in these categories:

  • security bug fixes
  • critical bug fixes (e.g., unavoidable/unrecoverable crashes, significant memory leaks)

No new features or improvements are in scope to be picked up in an LTS branch. A patch will not extend the maintenance or expiry date.

LTS releases may include additional extended support for security bug fixes as listed in the LTS schedule.

Schedule

This table shows previous LTS releases and end dates.

Release LTS Start Date Maintenance End Date
2022-06-07 <sub>patch 6 of 2021-03-18</sub> 2021-03-18 current

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (58)

Showing the top 5 NuGet packages that depend on Microsoft.Azure.Devices.Client:

Package Downloads
Chia

This library Chia contains utils for internal Danpower Reporting and is used by serveral reports.

RaaLabs.Edge.Modules.EdgeHub The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Package Description

ASOL3D.CloudConnect.Core

Communication module, that allows to send and receive messages from Azure Service Bus queues or Azure IoT Hub

Iwell.CubeLib

Library to simplify the interaction with a cube and increase testability

Hexagon.SFx.Models

Package Description

GitHub repositories (16)

Showing the top 5 popular GitHub repositories that depend on Microsoft.Azure.Devices.Client:

Repository Stars
dotnet/samples
Sample code referenced by the .NET documentation
dotnet/iot
This repo includes .NET Core implementations for various IoT boards, chips, displays and PCBs.
Azure/iotedge
The IoT Edge OSS project
Azure/azure-iot-sdk-csharp
A C# SDK for connecting devices to Microsoft Azure IoT services
Azure/connectthedots
Connect tiny devices to Microsoft Azure services to build IoT solutions
Version Downloads Last updated
1.42.2 115,109 12/20/2023
1.42.1 27,650 12/12/2023
1.42.0 495,401 5/2/2023
1.41.3 757,172 11/17/2022
1.41.2 334,068 8/12/2022
1.41.1 61,755 8/2/2022
1.41.0 297,810 5/12/2022
1.41.0-preview-001 3,047 2/19/2022
1.40.0 394,678 1/28/2022
1.39.0 290,264 11/2/2021
1.38.1-preview-001 1,396 10/19/2021
1.38.0 214,546 8/11/2021
1.38.0-preview-001 2,840 6/9/2021
1.37.2 415,058 5/14/2021
1.37.1 67,947 5/6/2021
1.37.0 56,599 4/27/2021
1.36.9 358 12/30/2023
1.36.8 7,241 3/28/2023
1.36.7 1,428 1/24/2023
1.36.6 19,146 6/7/2022
1.36.5 1,127 5/11/2022
1.36.4 8,757 1/19/2022
1.36.3 29,436 10/20/2021
1.36.2 4,189 8/12/2021
1.36.1 15,272 6/23/2021
1.36.0 135,995 3/24/2021
1.35.0 266,107 2/8/2021
1.34.0 86,990 1/22/2021
1.33.1 332,302 11/6/2020
1.33.0 11,779 11/3/2020
1.32.0 102,095 10/16/2020
1.32.0-preview-001 31,417 10/14/2020
1.31.2 22,339 10/9/2020
1.31.1 24,063 10/2/2020
1.31.0 13,685 10/1/2020
1.30.0 51,307 9/17/2020
1.29.1-preview-003 1,079 9/22/2020
1.29.1-preview-002 2,896 7/15/2020
1.29.1-preview-001 4,290 7/13/2020
1.29.0-preview-004 81,233 11/21/2019
1.29.0-preview-002 23,485 3/13/2019
1.29.0-preview-001 5,951 1/22/2019
1.28.2 9,725 8/10/2021
1.28.1 1,918 9/24/2020
1.28.0 117,626 8/19/2020
1.27.0 258,278 7/9/2020
1.26.0 138,408 6/11/2020
1.25.0 229,531 4/3/2020
1.24.0 68,200 3/13/2020
1.23.2 63,822 2/27/2020
1.23.1 67,135 2/19/2020
1.23.0 34,556 2/13/2020
1.22.0 44,711 2/1/2020
1.21.4 28,372 1/24/2020
1.21.3 113,445 12/18/2019
1.21.2 81,881 11/16/2019
1.21.1 165,253 9/12/2019
1.21.0 114,941 7/27/2019
1.20.3 97,620 7/2/2019
1.20.2 44,103 6/7/2019
1.20.1 90,516 5/3/2019
1.20.0 58,232 4/10/2019
1.19.0 264,676 1/5/2019
1.18.1 146,963 10/9/2018
1.18.0 203,372 8/18/2018
1.17.1 63,086 7/27/2018
1.17.0 140,661 6/21/2018
1.17.0-preview-007 3,909 5/7/2018
1.17.0-preview-006 2,181 5/1/2018
1.17.0-preview-005 1,854 4/26/2018
1.17.0-preview-004 3,346 3/29/2018
1.17.0-preview-003 1,830 3/28/2018
1.17.0-preview-001 4,584 2/9/2018
1.7.2 33,636 6/13/2018
1.7.1 50,861 4/5/2018
1.7.0 19,395 3/14/2018
1.6.4 1,888 10/9/2018
1.6.3 2,503 3/14/2018
1.6.2 37,600 1/26/2018
1.6.1 25,215 12/22/2017
1.6.0 49,942 12/4/2017
1.6.0-preview-001 19,913 11/14/2017
1.5.2 58,117 10/24/2017
1.5.1 12,432 10/9/2017
1.5.0 27,978 9/9/2017
1.4.2 10,039 8/26/2017
1.4.1 14,009 8/10/2017
1.4.0 4,597 8/3/2017
1.3.1 17,387 7/14/2017
1.3.0 12,866 6/30/2017
1.2.13 12,510 6/16/2017
1.2.12 7,587 6/2/2017
1.2.11 6,887 5/20/2017
1.2.10 63,051 5/5/2017
1.2.9 10,847 4/21/2017
1.2.8 29,766 4/13/2017
1.2.6 53,248 3/24/2017
1.2.5 14,594 3/10/2017
1.2.4 9,421 2/24/2017
1.2.3 8,363 2/11/2017
1.2.2 5,094 1/28/2017
1.2.1 12,091 1/12/2017
1.1.3 4,409 12/13/2016
1.1.2 3,354 12/8/2016
1.0.22 9,029 11/17/2016
1.0.21 7,507 10/20/2016
1.0.20 10,190 9/24/2016
1.0.19 7,189 9/10/2016
1.0.18 4,180 8/27/2016
1.0.17 3,481 8/15/2016
1.0.16 8,296 7/30/2016
1.0.13 13,974 6/20/2016
1.0.12 5,569 6/7/2016
1.0.11 5,203 5/26/2016
1.0.10 1,852 5/26/2016
1.0.9 3,740 5/25/2016
1.0.7 8,280 5/9/2016
1.0.6 5,185 4/25/2016
1.0.5 10,750 4/9/2016
1.0.4 3,376 3/28/2016
1.0.3 32,613 3/14/2016
1.0.2 9,231 2/16/2016
1.0.1 4,089 2/4/2016
1.0.0-preview-010 6,965 1/16/2016
1.0.0-preview-009 4,216 12/23/2015
1.0.0-preview-007 5,192 12/1/2015
1.0.0-preview-006 5,106 11/3/2015
1.0.0-preview-005 3,284 10/21/2015
1.0.0-preview-004 2,837 10/17/2015
1.0.0-preview-003-1 3,917 9/29/2015