Inviare messaggi dal cloud al dispositivo con Hub IoT (.NET)Send messages from the cloud to your device with IoT Hub (.NET)

IntroduzioneIntroduction

L'hub IoT di Azure è un servizio completamente gestito che consente di abilitare comunicazioni bidirezionali affidabili e sicure tra milioni di dispositivi e un back-end della soluzione.Azure IoT Hub is a fully managed service that helps enable reliable and secure bi-directional communications between millions of devices and a solution back end. L'esercitazione Introduzione all'hub IoT di Azure illustra come creare un hub IoT, effettuare il provisioning dell'identità di un dispositivo al suo interno e creare il codice di un'app per dispositivi che invia messaggi dal dispositivo al cloud.The [Get started with IoT Hub] tutorial shows how to create an IoT hub, provision a device identity in it, and code a device app that sends device-to-cloud messages.

Questa esercitazione si basa su Introduzione all'hub IoT di Azure.This tutorial builds on [Get started with IoT Hub]. Illustra le operazioni seguenti:It shows you how to:

  • Dal back-end della soluzione inviare messaggi da cloud a dispositivo a un singolo dispositivo tramite l'hub IoT.From your solution back end, send cloud-to-device messages to a single device through IoT Hub.
  • Ricevere messaggi da cloud a dispositivo in un dispositivo.Receive cloud-to-device messages on a device.
  • Dal back-end della soluzione richiedere l'acknowledgement di recapito (feedback) per i messaggi inviati a un dispositivo dall'hub IoT.From your solution back end, request delivery acknowledgement (feedback) for messages sent to a device from IoT Hub.

Per altre informazioni sui messaggi da cloud a dispositivo, vedere laGuida per gli sviluppatori dell'hub IoT.You can find more information on cloud-to-device messages in the IoT Hub developer guide.

Al termine di questa esercitazione vengono eseguite due app console .NET:At the end of this tutorial, you run two .NET console apps:

  • SimulatedDevice, una versione modificata dell'app creata in Introduzione all'hub IoT di Azure, che si connette all'hub IoT e riceve messaggi da cloud a dispositivo.SimulatedDevice, a modified version of the app created in [Get started with IoT Hub], which connects to your IoT hub and receives cloud-to-device messages.
  • SendCloudToDevice, che invia un messaggio diretto dal cloud al dispositivo all'app per dispositivi tramite l'hub IoT e quindi riceve la conferma di recapito.SendCloudToDevice, which sends a cloud-to-device message to the device app through IoT Hub, and then receives its delivery acknowledgement.

Nota

L’hub IoT dispone del supporto SDK per molte piattaforme e linguaggi, tra cui C, Java e Javascript, tramite gli SDK del dispositivo IoT Azure.IoT Hub has SDK support for many device platforms and languages (including C, Java, and Javascript) through [Azure IoT device SDKs]. Per istruzioni dettagliate su come connettere il dispositivo al codice dell'esercitazione e in generale all'hub IoT di Azure, vedere la Guida per sviluppatori dell'hub IoT.For step-by-step instructions on how to connect your device to this tutorial's code, and generally to Azure IoT Hub, see the [IoT Hub developer guide].

Per completare l'esercitazione, sono necessari gli elementi seguenti:To complete this tutorial, you need the following:

  • Visual Studio 2015 o Visual Studio 2017Visual Studio 2015 or Visual Studio 2017
  • Un account Azure attivo.An active Azure account. Se non si ha un account, è possibile creare un account gratuito in pochi minuti.(If you don't have an account, you can create a free account in just a couple of minutes.)

Ricevere messaggi nell'app per dispositiviReceive messages in the device app

In questa sezione si modificherà l'app per dispositivi creata in Introduzione all'hub IoT di Azure per ricevere i messaggi diretti dal cloud al dispositivo dall'hub IoT.In this section, you'll modify the device app you created in [Get started with IoT Hub] to receive cloud-to-device messages from the IoT hub.

  1. In Visual Studio, nel progetto SimulatedDevice aggiungere il seguente metodo alla classe Program.In Visual Studio, in the SimulatedDevice project, add the following method to the Program class.

     private static async void ReceiveC2dAsync()
     {
         Console.WriteLine("\nReceiving cloud to device messages from service");
         while (true)
         {
             Message receivedMessage = await deviceClient.ReceiveAsync();
             if (receivedMessage == null) continue;
    
             Console.ForegroundColor = ConsoleColor.Yellow;
             Console.WriteLine("Received message: {0}", Encoding.ASCII.GetString(receivedMessage.GetBytes()));
             Console.ResetColor();
    
             await deviceClient.CompleteAsync(receivedMessage);
         }
     }
    

    Il metodo ReceiveAsync restituisce in modo asincrono il messaggio ricevuto nel momento in cui viene ricevuto dal dispositivo.The ReceiveAsync method asynchronously returns the received message at the time that it is received by the device. Restituisce null dopo un periodo di timeout specificabile (in questo caso viene usato il valore predefinito di un minuto).It returns null after a specifiable timeout period (in this case, the default of one minute is used). Quando l'app riceve un valore Null, deve rimanere in attesa di nuovi messaggi.When the app receives a null, it should continue to wait for new messages. Questo requisito è il motivo per la riga if (receivedMessage == null) continue.This requirement is the reason for the if (receivedMessage == null) continue line.

    La chiamata a CompleteAsync() notifica all'hub IoT che il messaggio è stato elaborato correttamente.The call to CompleteAsync() notifies IoT Hub that the message has been successfully processed. Il messaggio può essere rimosso dalla coda del dispositivo in modo sicuro.The message can be safely removed from the device queue. Se si è verificato un evento che ha impedito all'app per dispositivo di completare l'elaborazione del messaggio, l'hub IoT lo recapita nuovamente.If something happened that prevented the device app from completing the processing of the message, IoT Hub delivers it again. È quindi importante che la logica di elaborazione del messaggio nell'app per dispositivo sia idempotente, in modo che la ricezione dello stesso messaggio più volte produca lo stesso risultato.It is then important that message processing logic in the device app is idempotent, so that receiving the same message multiple times produces the same result. Un'applicazione può anche abbandonare temporaneamente un messaggio e, di conseguenza, l'hub IoT mantiene il messaggio nella coda per un uso futuro.An application can also temporarily abandon a message, which results in IoT hub retaining the message in the queue for future consumption. In alternativa, l'applicazione può rifiutare un messaggio, rimuovendolo così definitivamente dalla coda.Or, the application can reject a message, which permanently removes the message from the queue. Per altre informazioni sul ciclo di vita del messaggio da cloud a dispositivo, vedere Guida per gli sviluppatori dell'hub IoT.For more information about the cloud-to-device message lifecycle, see the IoT Hub developer guide.

    Nota

    Quando si usa HTTPS invece di MQTT o AMQP come trasporto, il metodo ReceiveAsync verrà restituito immediatamente.When using HTTPS instead of MQTT or AMQP as a transport, the ReceiveAsync method returns immediately. Il modello supportato per i messaggi da cloud a dispositivo con HTTPS è rappresentato da dispositivi collegati in modo intermittente che controllano raramente la presenza di messaggi (meno di ogni 25 minuti).The supported pattern for cloud-to-device messages with HTTPS is intermittently connected devices that check for messages infrequently (less than every 25 minutes). La generazione di altre ricezioni HTTPS comporta la limitazione delle richieste da parte dell'hub IoT.Issuing more HTTPS receives results in IoT Hub throttling the requests. Per altre informazioni sulle differenze tra il supporto di MQTT, AMQP e HTTPS e sulla limitazione delle richieste dell'hub IoT, vedere la Guida per gli sviluppatori dell'hub IoT.For more information about the differences between MQTT, AMQP and HTTPS support, and IoT Hub throttling, see the IoT Hub developer guide.

  2. Aggiungere il metodo seguente al metodo Main immediatamente prima della riga Console.ReadLine():Add the following method in the Main method, right before the Console.ReadLine() line:

     ReceiveC2dAsync();
    

Nota

Per semplicità, in questa esercitazione non si implementa alcun criterio di nuovi tentativi.For simplicity's sake, this tutorial does not implement any retry policy. Nel codice di produzione è consigliabile implementare criteri di ripetizione dei tentativi, ad esempio un backoff esponenziale, come indicato nell'articolo di MSDN Transient Fault Handling.In production code, you should implement retry policies (such as exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Inviare un messaggio da cloud a dispositivoSend a cloud-to-device message

In questa sezione viene scritta un'app console di .NET che invia messaggi da cloud a dispositivo all'app per dispositivi.In this section, you write a .NET console app that sends cloud-to-device messages to the device app.

  1. Nella soluzione di Visual Studio corrente creare un progetto di applicazioni desktop in Visual C# usando il modello di progetto Applicazione console.In the current Visual Studio solution, create a Visual C# Desktop App project by using the Console Application project template. Denominare il progetto SendCloudToDevice.Name the project SendCloudToDevice.

    Nuovo progetto in Visual Studio

  2. In Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione e quindi scegliere Gestisci pacchetti NuGet per la soluzione.In Solution Explorer, right-click the solution, and then click Manage NuGet Packages for Solution....

    L'azione consente di visualizzare la finestra Gestisci pacchetti NuGet.This action opens the Manage NuGet Packages window.

  3. Cercare Microsoft.Azure.Devices, fare clic su Installa e quindi accettare le condizioni per l'uso.Search for Microsoft.Azure.Devices, click Install, and accept the terms of use.

    Verrà quindi scaricato e installato il pacchetto NuGet Azure IoT Service SDK e verrà aggiunto un riferimento a tale pacchetto.This downloads, installs, and adds a reference to the [Azure IoT service SDK NuGet package].

  4. Aggiungere l'istruzione using seguente all'inizio del file Program.cs :Add the following using statement at the top of the Program.cs file:

     using Microsoft.Azure.Devices;
    
  5. Aggiungere i campi seguenti alla classe Program .Add the following fields to the Program class. Sostituire il valore del segnaposto con la stringa di connessione all'hub IoT da Introduzione all'hub IoT di Azure:Substitute the placeholder value with the IoT hub connection string from [Get started with IoT Hub]:

     static ServiceClient serviceClient;
     static string connectionString = "{iot hub connection string}";
    
  6. Aggiungere il metodo seguente alla classe Program :Add the following method to the Program class:

     private async static Task SendCloudToDeviceMessageAsync()
     {
         var commandMessage = new Message(Encoding.ASCII.GetBytes("Cloud to device message."));
         await serviceClient.SendAsync("myFirstDevice", commandMessage);
     }
    

    Questo metodo invia un nuovo messaggio da cloud a dispositivo al dispositivo con ID myFirstDevice.This method sends a new cloud-to-device message to the device with the ID, myFirstDevice. Modificare questo parametro solo nel caso in cui sia stato modificato rispetto a quello usato in Introduzione all'hub IoT di Azure.Change this parameter only if you modified it from the one used in [Get started with IoT Hub].

  7. Aggiungere infine le righe seguenti al metodo Main :Finally, add the following lines to the Main method:

     Console.WriteLine("Send Cloud-to-Device message\n");
     serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
    
     Console.WriteLine("Press any key to send a C2D message.");
     Console.ReadLine();
     SendCloudToDeviceMessageAsync().Wait();
     Console.ReadLine();
    
  8. In Visual Studio fare clic con il pulsante destro del mouse sulla soluzione e selezionare Imposta progetti di avvio. Selezionare Progetti di avvio multipli, quindi selezionare l'azione Start per ReadDeviceToCloudMessages, SimulatedDevice e SendCloudToDevice.From within Visual Studio, right-click your solution, and select Set StartUp projects.... Select Multiple startup projects, then select the Start action for ReadDeviceToCloudMessages, SimulatedDevice, and SendCloudToDevice.
  9. Premere F5.Press F5. Devono avviarsi tutte e tre le applicazioni.All three applications should start. Selezionare la finestra SendCloudToDevice e premere INVIO.Select the SendCloudToDevice windows, and press Enter. Verrà visualizzato il messaggio ricevuto dall'app per dispositivi.You should see the message being received by the device app.

    Ricezione di un messaggio da parte dell'app

Ricevere feedback di recapitoReceive delivery feedback

È possibile richiedere la conferma della ricezione (o della scadenza) dall'hub IoT per ogni messaggio da cloud a dispositivo.It is possible to request delivery (or expiration) acknowledgements from IoT Hub for each cloud-to-device message. Questa opzione consente al back-end della soluzione di informare facilmente la logica di ripetizione o di compensazione.This option enables the solution back end to easily inform retry or compensation logic. Per altre informazioni sul feedback da cloud a dispositivo, vedere Guida per gli sviluppatori dell'hub IoT.For more information about cloud-to-device feedback, see the IoT Hub developer guide.

In questa sezione viene modificata l'app SendCloudToDevice per richiedere feedback e riceverli dall'hub IoT.In this section, you modify the SendCloudToDevice app to request feedback, and receive it from IoT Hub.

  1. In Visual Studio, nel progetto SendCloudToDevice aggiungere il seguente metodo alla classe Programma.In Visual Studio, in the SendCloudToDevice project, add the following method to the Program class.

     private async static void ReceiveFeedbackAsync()
     {
         var feedbackReceiver = serviceClient.GetFeedbackReceiver();
    
         Console.WriteLine("\nReceiving c2d feedback from service");
         while (true)
         {
             var feedbackBatch = await feedbackReceiver.ReceiveAsync();
             if (feedbackBatch == null) continue;
    
             Console.ForegroundColor = ConsoleColor.Yellow;
             Console.WriteLine("Received feedback: {0}", string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
             Console.ResetColor();
    
             await feedbackReceiver.CompleteAsync(feedbackBatch);
         }
     }
    

    Si noti che il modello di ricezione è identico a quello usato per ricevere messaggi da cloud a dispositivo dall'app per dispositivo.Note this receive pattern is the same one used to receive cloud-to-device messages from the device app.

  2. Aggiungere il metodo seguente nel metodo MainserviceClient = ServiceClient.CreateFromConnectionString(connectionString) immediatamente dopo la riga :Add the following method in the Main method, right after the serviceClient = ServiceClient.CreateFromConnectionString(connectionString) line:

     ReceiveFeedbackAsync();
    
  3. Per richiedere feedback del recapito del messaggio da cloud a dispositivo, è necessario specificare una proprietà nel metodo SendCloudToDeviceMessageAsync .To request feedback for the delivery of your cloud-to-device message, you have to specify a property in the SendCloudToDeviceMessageAsync method. Aggiungere la riga seguente, subito dopo la riga var commandMessage = new Message(...); :Add the following line, right after the var commandMessage = new Message(...); line:

     commandMessage.Ack = DeliveryAcknowledgement.Full;
    
  4. Premere F5per eseguire le app.Run the apps by pressing F5. Si dovrebbero avviare tutte e tre le applicazioni.You should see all three applications start. Selezionare la finestra SendCloudToDevice e premere INVIO.Select the SendCloudToDevice windows, and press Enter. Verrà visualizzata la ricezione del messaggio da parte dell'app per dispositivi e, dopo alcuni secondi, la ricezione del messaggio di feedback da parte dell'applicazione SendCloudToDevice.You should see the message being received by the device app, and after a few seconds, the feedback message being received by your SendCloudToDevice application.

    Ricezione di un messaggio da parte dell'app

Nota

Per semplicità, in questa esercitazione non si implementa alcun criterio di nuovi tentativi.For simplicity's sake, this tutorial does not implement any retry policy. Nel codice di produzione è consigliabile implementare criteri di ripetizione dei tentativi, ad esempio un backoff esponenziale, come indicato nell'articolo di MSDN Transient Fault Handling.In production code, you should implement retry policies (such as exponential backoff), as suggested in the MSDN article Transient Fault Handling.

Passaggi successiviNext steps

In questa esercitazione è stato descritto come inviare e ricevere messaggi da cloud a dispositivo.In this tutorial, you learned how to send and receive cloud-to-device messages.

Per avere degli esempi di soluzioni complete che utilizzano l'hub IoT, vedere la Azure IoT Suite.To see examples of complete end-to-end solutions that use IoT Hub, see Azure IoT Suite.

Per altre informazioni sullo sviluppo delle soluzioni con l'hub IoT, vedere la Guida per sviluppatori dell'hub IoT.To learn more about developing solutions with IoT Hub, see the [IoT Hub developer guide].