You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 article describes how to use the [Azure IoT SDK for .NET](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/readme.md) to create device and backend service application code to receive and send cloud-to-device messages.
14
+
15
+
## Create a device application
16
+
17
+
This section describes how to receive cloud-to-device messages.
14
18
15
19
There are two options that a device client application can use to receive messages:
16
20
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.
18
21
***Callback**: The device application sets up an asynchronous message handler method that is called immediately when a message arrives.
22
+
***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.
The [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class exposes all the methods required to receive messages on the device.
51
+
30
52
### Supply the connection parameters
31
53
32
54
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 +57,38 @@ Supply the IoT Hub primary connection string and Device ID to `DeviceClient` usi
35
57
*`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).
36
58
*`ClientOptions` - Options that allow configuration of the device or module client instance during initialization.
37
59
38
-
This example calls `CreateFromConnectionString`to define the `DeviceClient` connection IoT hub and device ID settings.
60
+
This example connects to a device using the `Mqtt` transport protocol.
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.
72
+
73
+
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.
74
+
75
+
Callback is available only using these protocols:
76
+
77
+
*`Mqtt`
78
+
*`Mqtt_WebSocket_Only`
79
+
*`Mqtt_Tcp_Only`
80
+
*`Amqp`
81
+
*`Amqp_WebSocket_Only`
82
+
*`Amqp_Tcp_only`
83
+
84
+
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.
85
+
86
+
In this example, `SetReceiveMessageHandlerAsync` sets up a callback handler method named `OnC2dMessageReceivedAsync`, which is called each time a message is received.
87
+
88
+
```csharp
89
+
// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");
44
92
```
45
93
46
94
### Polling
@@ -109,31 +157,6 @@ while (!stopPolling)
109
157
}
110
158
```
111
159
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).
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");
135
-
```
136
-
137
160
### Receive message retry policy
138
161
139
162
The device client message retry policy can be defined using [DeviceClient.SetRetryPolicy](/dotnet/api/microsoft.azure.devices.client.deviceclient.setretrypolicy).
@@ -144,35 +167,46 @@ The message retry timeout is stored in the [DeviceClient.OperationTimeoutInMilli
144
167
145
168
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.
146
169
147
-
## Send cloud-to-device messages
170
+
## Create a backend application
148
171
149
172
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.
150
173
151
174
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.
152
175
153
-
### Declare a ServiceClient object
176
+
### Add service NuGet Package
154
177
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.
178
+
Backend service applications require the **Microsoft.Azure.Devices** NuGet package.
156
179
157
-
```csharp
158
-
staticServiceClientserviceClient;
159
-
```
180
+
### Connect to IoT hub
181
+
182
+
You can connect a backend service to IoT Hub using the following methods:
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:
193
+
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:
164
194
165
195
*`transportType` - `Amqp` or `Amqp_WebSocket_Only`.
166
196
*`transportSettings` - The AMQP and HTTP proxy settings for Service Client.
167
197
*`ServiceClientOptions` - Options that allow configuration of the service client instance during initialization. For more information, see [ServiceClientOptions](/dotnet/api/microsoft.azure.devices.serviceclientoptions).
168
198
169
-
This example creates the `ServiceClient` object using the IoT Hub connection string.
199
+
This example creates the `ServiceClient` object using the IoT Hub connection string and default `Amqp` transport.
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.
* Send cloud-to-device messages from a backend application
17
+
18
+
## Receive cloud-to-device messages on a device
12
19
13
20
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.
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:
30
48
@@ -39,7 +57,7 @@ The [DeviceClient](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient?#co
**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.
148
166
149
-
## Send cloud-to-device messages
167
+
## Send cloud-to-device messages from a backend application
150
168
151
169
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.
152
170
@@ -174,24 +192,34 @@ import java.io.IOException;
174
192
importjava.net.URISyntaxException;
175
193
```
176
194
177
-
### Define the connection protocol
195
+
### Connect to the IoT Hub
196
+
197
+
You can connect a backend service to IoT Hub using the following methods:
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.
180
209
181
210
`IotHubServiceClientProtocol` only accepts the `AMQPS` or `AMQPS_WS` enum.
### Open a feedback receiver for message delivery feedback
206
238
207
239
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 +286,7 @@ if (feedbackBatch != null) {
254
286
255
287
### SDK send message samples
256
288
257
-
*[Service client sample](/java/api/overview/azure/iot?example) - Send message example, #1.
289
+
There are two send message samples:
258
290
291
+
*[Service client sample](/java/api/overview/azure/iot?example) - Send message example, #1.
259
292
*[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