Skip to content

Commit d4a43e4

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #292295 from gsteve88/add-cert-entra-c2d-messages
Updated article to add cert and Entra auth steps
2 parents 885807e + d5e17f1 commit d4a43e4

5 files changed

+273
-128
lines changed

‎articles/iot-hub/how-to-cloud-to-device-messaging.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ author: kgremban
66
ms.author: kgremban
77
ms.service: azure-iot-hub
88
ms.topic: how-to
9-
ms.date: 06/20/2024
9+
ms.date: 12/19/2024
1010
zone_pivot_groups: iot-hub-howto-c2d-1
1111
ms.custom: [amqp, mqtt, "Role: Cloud Development", "Role: IoT Device"]
1212
---

‎includes/iot-hub-howto-cloud-to-device-messaging-dotnet.md

Lines changed: 78 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,43 @@ ms.author: kgremban
44
ms.service: azure-iot-hub
55
ms.devlang: csharp
66
ms.topic: include
7-
ms.date: 06/20/2024
7+
ms.date: 12/19/2024
88
ms.custom: [amqp, mqtt, "Role: Cloud Development", "Role: IoT Device", devx-track-csharp, devx-track-dotnet]
99
---
1010

11-
## Receive cloud-to-device messages
11+
## Create a device application
1212

13-
This section describes how to receive cloud-to-device messages using the [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class in the Azure IoT SDK for .NET.
13+
This section describes how to receive cloud-to-device messages.
1414

1515
There are two options that a device client application can use to receive messages:
1616

17-
* **Polling**: The device application checks for new IoT Hub messages using a code loop (for example, a `while` or `for` loop). The loop executes continually, checking for messages.
1817
* **Callback**: The device application sets up an asynchronous message handler method that is called immediately when a message arrives.
18+
* **Polling**: The device application checks for new IoT Hub messages using a code loop (for example, a `while` or `for` loop). The loop executes continually, checking for messages.
1919

20-
### Declare a DeviceClient object
20+
### Required device NuGet Package
2121

22-
[DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) includes methods and properties necessary to receive messages from IoT Hub.
22+
Device client applications written in C# require the **Microsoft.Azure.Devices.Client** NuGet package.
2323

24-
For example:
24+
Add these `using` statements to use the device library.
2525

2626
```csharp
27-
static DeviceClient deviceClient;
27+
using Microsoft.Azure.Devices.Client;
28+
using Microsoft.Azure.Devices.Shared;
2829
```
2930

31+
### Connect a device to IoT Hub
32+
33+
A device app can authenticate with IoT Hub using the following methods:
34+
35+
* Shared access key
36+
* X.509 certificate
37+
38+
[!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
39+
40+
#### Authenticate using a shared access key
41+
42+
The [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class exposes all the methods required to receive messages on the device.
43+
3044
### Supply the connection parameters
3145

3246
Supply the IoT Hub primary connection string and Device ID to `DeviceClient` using the [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.client.deviceclient.createfromconnectionstring) method. In addition to the required IoT Hub primary connection string, the `CreateFromConnectionString` method can be overloaded to include these *optional* parameters:
@@ -35,12 +49,42 @@ Supply the IoT Hub primary connection string and Device ID to `DeviceClient` usi
3549
* `transportSettings` - Interface used to define various transport-specific settings for `DeviceClient` and `ModuleClient`. For more information, see [ITransportSettings Interface](/dotnet/api/microsoft.azure.devices.client.itransportsettings).
3650
* `ClientOptions` - Options that allow configuration of the device or module client instance during initialization.
3751

38-
This example calls `CreateFromConnectionString` to define the `DeviceClient` connection IoT hub and device ID settings.
52+
This example connects to a device using the `Mqtt` transport protocol.
3953

40-
``` csharp
41-
static string connectionString = "{your IoT hub connection string}";
42-
static string deviceID = "{your device ID}";
43-
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);
54+
```csharp
55+
static string DeviceConnectionString = "{IoT hub device connection string}";
56+
static deviceClient = null;
57+
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString,
58+
TransportType.Mqtt);
59+
```
60+
61+
#### Authenticate using an X.509 certificate
62+
63+
[!INCLUDE [iot-hub-howto-auth-device-cert-dotnet](iot-hub-howto-auth-device-cert-dotnet.md)]
64+
65+
### Callback
66+
67+
To receive callback cloud-to-device messages in the device application, the application must connect to the IoT Hub and set up a callback listener to process incoming messages. Incoming messages to the device are received from the IoT Hub message queue.
68+
69+
Using callback, the device application sets up a message handler method using [SetReceiveMessageHandlerAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.setreceivemessagehandlerasync). The message handler is called then a message is received. Creating a callback method to receive messages removes the need to continuously poll for received messages.
70+
71+
Callback is available only using these protocols:
72+
73+
* `Mqtt`
74+
* `Mqtt_WebSocket_Only`
75+
* `Mqtt_Tcp_Only`
76+
* `Amqp`
77+
* `Amqp_WebSocket_Only`
78+
* `Amqp_Tcp_only`
79+
80+
The `Http1` protocol option does not support callbacks since the SDK methods would need to poll for received messages anyway, which defeats the callback principle.
81+
82+
In this example, `SetReceiveMessageHandlerAsync` sets up a callback handler method named `OnC2dMessageReceivedAsync`, which is called each time a message is received.
83+
84+
```csharp
85+
// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
86+
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
87+
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");
4488
```
4589

4690
### Polling
@@ -109,31 +153,6 @@ while (!stopPolling)
109153
}
110154
```
111155

112-
### Callback
113-
114-
To receive callback cloud-to-device messages in the device application, the application must connect to the IoT Hub and set up a callback listener to process incoming messages. Incoming messages to the device are received from the IoT Hub message queue.
115-
116-
Using callback, the device application sets up a message handler method using [SetReceiveMessageHandlerAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.setreceivemessagehandlerasync). The message handler is called then a message is received. Creating a callback method to receive messages removes the need to continuously poll for received messages.
117-
118-
Callback is available only using these protocols:
119-
120-
* `Mqtt`
121-
* `Mqtt_WebSocket_Only`
122-
* `Mqtt_Tcp_Only`
123-
* `Amqp`
124-
* `Amqp_WebSocket_Only`
125-
* `Amqp_Tcp_only`
126-
127-
The `Http1` protocol option does not support callbacks since the SDK methods would need to poll for received messages anyway, which defeats the callback principle.
128-
129-
In this example, `SetReceiveMessageHandlerAsync` sets up a callback handler method named `OnC2dMessageReceivedAsync`, which is called each time a message is received.
130-
131-
```csharp
132-
// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
133-
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
134-
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");
135-
```
136-
137156
### Receive message retry policy
138157

139158
The device client message retry policy can be defined using [DeviceClient.SetRetryPolicy](/dotnet/api/microsoft.azure.devices.client.deviceclient.setretrypolicy).
@@ -144,35 +163,46 @@ The message retry timeout is stored in the [DeviceClient.OperationTimeoutInMilli
144163

145164
The .NET/C# SDK includes a [Message Receive](https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/device/samples/getting%20started/MessageReceiveSample) sample that includes the receive message methods described in this section.
146165

147-
## Send cloud-to-device messages
166+
## Create a backend application
148167

149168
This section describes essential code to send a message from a solution backend application to an IoT device using the [ServiceClient](/dotnet/api/microsoft.azure.devices.serviceclient) class in the Azure IoT SDK for .NET. As discussed previously, a solution backend application connects to an IoT Hub and messages are sent to IoT Hub encoded with a destination device. IoT Hub stores incoming messages to its message queue, and messages are delivered from the IoT Hub message queue to the target device.
150169

151170
A solution backend application can also request and receive delivery feedback for a message sent to IoT Hub that is destined for device delivery via the message queue.
152171

153-
### Declare a ServiceClient object
172+
### Add service NuGet Package
154173

155-
[ServiceClient](/dotnet/api/microsoft.azure.devices.serviceclient) includes methods and properties necessary to send messages from an application through IoT Hub to a device.
174+
Backend service applications require the **Microsoft.Azure.Devices** NuGet package.
156175

157-
``` csharp
158-
static ServiceClient serviceClient;
159-
```
176+
### Connect to IoT hub
177+
178+
You can connect a backend service to IoT Hub using the following methods:
179+
180+
* Shared access policy
181+
* Microsoft Entra
182+
183+
[!INCLUDE [iot-authentication-service-connection-string.md](iot-authentication-service-connection-string.md)]
160184

161-
### Supply the connection string
185+
#### Connect using a shared access policy
162186

163-
Supply the IoT Hub primary connection string to `ServiceClient` using the [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.serviceclient.createfromconnectionstring) method. In addition to the required IoT Hub primary connection string, the `CreateFromConnectionString` method can be overloaded to include these *optional* parameters:
187+
##### Supply the connection string
188+
189+
Connect a backend application to a device using [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.serviceclient.createfromconnectionstring). In addition to the required IoT Hub primary connection string, the `CreateFromConnectionString` method can be overloaded to include these *optional* parameters:
164190

165191
* `transportType` - `Amqp` or `Amqp_WebSocket_Only`.
166192
* `transportSettings` - The AMQP and HTTP proxy settings for Service Client.
167193
* `ServiceClientOptions` - Options that allow configuration of the service client instance during initialization. For more information, see [ServiceClientOptions](/dotnet/api/microsoft.azure.devices.serviceclientoptions).
168194

169-
This example creates the `ServiceClient` object using the IoT Hub connection string.
195+
This example creates the `ServiceClient` object using the IoT Hub connection string and default `Amqp` transport.
170196

171197
``` csharp
172-
static string connectionString = "{your iot hub connection string}";
198+
static string connectionString = "{your IoT hub connection string}";
173199
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
174200
```
175201

202+
#### Connect using Microsoft Entra
203+
204+
[!INCLUDE [iot-hub-howto-connect-service-iothub-entra-dotnet](iot-hub-howto-connect-service-iothub-entra-dotnet.md)]
205+
176206
### Send an asynchronous cloud-to-device message
177207

178208
Use [sendAsync](/dotnet/api/microsoft.azure.devices.serviceclient.sendasync) to send an asynchronous message from an application through the cloud (IoT Hub) to the device. The call is made using the AMQP protocol.

‎includes/iot-hub-howto-cloud-to-device-messaging-java.md

Lines changed: 42 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ ms.author: kgremban
44
ms.service: azure-iot-hub
55
ms.devlang: java
66
ms.topic: include
7-
ms.date: 06/20/2024
7+
ms.date: 12/19/2024
88
ms.custom: [amqp, mqtt, devx-track-java, devx-track-extended-java]
99
---
1010

11-
## Receive cloud-to-device messages
11+
## Create a device application
1212

1313
This section describes how to receive cloud-to-device messages using the [DeviceClient](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient) class from the Azure IoT SDK for Java.
1414

15-
For a Java-based device application to receive cloud-to-device messages, it must connect to IoT Hub, then set up a callback listener and message handler to process incoming messages from IoT Hub. The device application should also be able to detect and handle disconnects in case the device-to-IoT Hub message connection is broken.
15+
For a Java-based device application to receive cloud-to-device messages, it must connect to IoT Hub, then set up a callback listener and message handler to process incoming messages from IoT Hub.
1616

1717
### Import Azure IoT Java SDK libraries
1818

@@ -24,7 +24,16 @@ import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
2424
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
2525
```
2626

27-
### Declare a DeviceClient object
27+
### Connect a device to IoT Hub
28+
29+
A device app can authenticate with IoT Hub using the following methods:
30+
31+
* Shared access key
32+
* X.509 certificate
33+
34+
[!INCLUDE [iot-authentication-device-connection-string.md](iot-authentication-device-connection-string.md)]
35+
36+
#### Authenticate using a shared access key
2837

2938
The [DeviceClient](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient?#com-microsoft-azure-sdk-iot-device-deviceclient-deviceclient(java-lang-string-com-microsoft-azure-sdk-iot-device-iothubclientprotocol)) object instantiation requires these parameters:
3039

@@ -39,11 +48,15 @@ The [DeviceClient](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient?#co
3948
For example:
4049

4150
```java
42-
static string connectionString = "{a device connection string}";
51+
static string connectionString = "{IOT hub device connection string}";
4352
static protocol = IotHubClientProtocol.AMQPS;
4453
DeviceClient client = new DeviceClient(connectionString, protocol);
4554
```
4655

56+
#### Authenticate using an X.509 certificate
57+
58+
[!INCLUDE [iot-hub-howto-auth-device-cert-java](iot-hub-howto-auth-device-cert-java.md)]
59+
4760
### Set the message callback method
4861

4962
Use the [setMessageCallback](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient?com-microsoft-azure-sdk-iot-device-deviceclient-setmessagecallback(com-microsoft-azure-sdk-iot-device-messagecallback-java-lang-object)) method to define a message handler method that is notified when a message is received from IoT Hub.
@@ -146,7 +159,7 @@ client.open(true);
146159

147160
**HandleMessages**: a sample device app included with the [Microsoft Azure IoT SDK for Java](https://github.com/Azure/azure-iot-sdk-java/tree/main/iothub/device/iot-device-samples), which connects to your IoT hub and receives cloud-to-device messages.
148161

149-
## Send cloud-to-device messages
162+
## Create a backend application
150163

151164
This section describes how to send a cloud-to-device message using the [ServiceClient](/java/api/com.azure.core.annotation.serviceclient) class from the Azure IoT SDK for Java. A solution backend application connects to an IoT Hub and messages are sent to IoT Hub encoded with a destination device. IoT Hub stores incoming messages to its message queue, and messages are delivered from the IoT Hub message queue to the target device.
152165

@@ -174,34 +187,48 @@ import java.io.IOException;
174187
import java.net.URISyntaxException;
175188
```
176189

177-
### Define the connection protocol
190+
### Connect to the IoT Hub
191+
192+
You can connect a backend service to IoT Hub using the following methods:
193+
194+
* Shared access policy
195+
* Microsoft Entra
196+
197+
[!INCLUDE [iot-authentication-service-connection-string.md](iot-authentication-service-connection-string.md)]
198+
199+
#### Connect using a shared access policy
200+
201+
##### Define the connection protocol
178202

179203
Use [IotHubServiceClientProtocol](/java/api/com.microsoft.azure.sdk.iot.service.iothubserviceclientprotocol) to define the application-layer protocol used by the service client to communicate with an IoT Hub.
180204

181205
`IotHubServiceClientProtocol` only accepts the `AMQPS` or `AMQPS_WS` enum.
182206

183207
```java
184-
private static final IotHubServiceClientProtocol protocol =
185-
IotHubServiceClientProtocol.AMQPS;
208+
IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;
186209
```
187210

188-
### Create the ServiceClient object
211+
##### Create the ServiceClient object
189212

190213
Create the [ServiceClient](/java/api/com.azure.core.annotation.serviceclient) object, supplying the Iot Hub connection string and protocol.
191214

192215
```java
193-
private static final String connectionString = "{yourhubconnectionstring}";
194-
private static final ServiceClient serviceClient (connectionString, protocol);
216+
String connectionString = "{yourhubconnectionstring}";
217+
ServiceClient serviceClient (connectionString, protocol);
195218
```
196219

197-
### Open the connection between application and IoT Hub
220+
##### Open the connection between application and IoT Hub
198221

199222
[open](/java/api/com.microsoft.azure.sdk.iot.service.serviceclient?#com-microsoft-azure-sdk-iot-service-serviceclient-open()) the AMQP sender connection. This method creates the connection between the application and IoT Hub.
200223

201224
```java
202225
serviceClient.open();
203226
```
204227

228+
#### Connect using Microsoft Entra
229+
230+
[!INCLUDE [iot-hub-howto-connect-service-iothub-entra-java](iot-hub-howto-connect-service-iothub-entra-java.md)]
231+
205232
### Open a feedback receiver for message delivery feedback
206233

207234
You can use a [FeedbackReceiver](/java/api/com.microsoft.azure.sdk.iot.service.feedbackreceiver) to get sent message delivery to IoT Hub feedback. A `FeedbackReceiver` is a specialized receiver whose `Receive` method returns a `FeedbackBatch` instead of a `Message`.
@@ -254,6 +281,7 @@ if (feedbackBatch != null) {
254281

255282
### SDK send message samples
256283

257-
* [Service client sample](/java/api/overview/azure/iot?example) - Send message example, #1.
284+
There are two send message samples:
258285

286+
* [Service client sample](/java/api/overview/azure/iot?example) - Send message example, #1.
259287
* [Service client sample](https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/service/samples/getting%20started/ServiceClientSample) - Send message example, #2.

0 commit comments

Comments
 (0)