Upload files from your device to the cloud with IoT Hub (.Net)

  • Article
  • 14 minutes to read
  • .NET
  • Java
  • Node.js
  • Python

This tutorial shows you how to use the file upload feature of IoT Hub with the Azure IoT .Net device and service SDKs.

The Send telemetry from a device to an IoT hub quickstart and Send cloud-to-device messages with IoT Hub tutorial prove the basic device-to-deject and cloud-to-device messaging functionality of IoT Hub. The Configure Bulletin Routing with IoT Hub tutorial describes a mode to reliably shop device-to-deject letters in Microsoft Azure hulk storage. However, in some scenarios yous can't easily map the data your devices ship into the relatively small-scale device-to-deject letters that IoT Hub accepts. For case:

  • Large files that incorporate images

  • Videos

  • Vibration information sampled at loftier frequency

  • Some class of preprocessed data

These files are typically batch candy in the cloud using tools such every bit Azure Data Manufacturing plant or the Hadoop stack. When you need to upload files from a device, however, yous tin can still use the security and reliability of IoT Hub. This tutorial shows yous how.

At the end of this tutorial you run two .NET console apps:

  • FileUploadSample. This device app uploads a file to storage using a SAS URI provided by your IoT hub. You'll run this app from the Azure IoT C# samples repository that you lot download in the prerequisites.

  • ReadFileUploadNotification. This service app receives file upload notifications from your IoT hub. Yous'll create this app.

Note

IoT Hub supports many device platforms and languages, including C, Java, Python, and JavaScript, through Azure IoT device SDKs. Refer to the Azure IoT Developer Eye for step-past-step instructions on how to connect your device to Azure IoT Hub.

Prerequisites

  • An active Azure business relationship. If you lot don't have an business relationship, you can create a costless business relationship in only a couple of minutes.

  • The sample applications y'all run in this article are written using C#. For the Azure IoT C# samples, we recommend you accept the .NET Core SDK 3.1 or greater on your evolution machine.

    You can download the .Cyberspace Cadre SDK for multiple platforms from .Net.

    You can verify the current version of the .NET Core SDK on your evolution automobile using the following control:

                      dotnet --version

  • Download the Azure IoT C# samples from https://github.com/Azure-Samples/azure-iot-samples-csharp/annal/main.nil and extract the ZIP annal.

  • Make sure that port 8883 is open in your firewall. The sample in this article uses MQTT protocol, which communicates over port 8883. This port may exist blocked in some corporate and educational network environments. For more information and ways to work around this issue, run across Connecting to IoT Hub (MQTT).

Create an IoT hub

This section describes how to create an IoT hub using the Azure portal.

  1. Sign in to the Azure portal.

  2. On the Azure homepage, select the + Create a resource button.

  3. From the Categories menu, select Internet of Things then IoT Hub.

  4. On the Basics tab, complete the fields every bit follows:

    • Subscription: Select the subscription to utilize for your hub.

    • Resources grouping: Select a resource grouping or create a new i. To create a new one, select Create new and make full in the proper noun you want to use. To use an existing resources grouping, select that resources group. For more information, see Manage Azure Resource Manager resources groups.

    • Region: Select the region in which you want your hub to be located. Select the location closest to you. Some features, such as IoT Hub device streams, are merely available in specific regions. For these express features, you lot must select one of the supported regions.

    • IoT hub name: Enter a proper noun for your hub. This proper noun must exist globally unique, with a length between 3 and 50 alphanumeric characters. The name can also include the dash ('-') character.

    Important

    Because the IoT hub will be publicly discoverable every bit a DNS endpoint, be certain to avoid entering any sensitive or personally identifiable data when you name it.

    Create a hub in the Azure portal.

  5. Select Next: Networking to continue creating your hub.

    Choose the endpoints that devices tin use to connect to your IoT hub. You can select the default setting, Public access, or choose Private access. Accept the default setting for this example.

    Choose the endpoints that can connect.

  6. Select Next: Direction to keep creating your hub.

    Set the size and scale for a new hub using the Azure portal.

    You can accept the default settings hither. If desired, you can modify any of the following fields:

    • Pricing and scale tier: Your selected tier. You can cull from several tiers, depending on how many features y'all desire and how many messages y'all send through your solution per day. The complimentary tier is intended for testing and evaluation. It allows 500 devices to be connected to the hub and up to 8,000 messages per twenty-four hours. Each Azure subscription can create ane IoT hub in the costless tier.

      If you are working through a quickstart, select the gratuitous tier.

    • IoT Hub units: The number of messages immune per unit per day depends on your hub's pricing tier. For example, if you want the hub to back up ingress of 700,000 messages, you choose two S1 tier units. For details about the other tier options, see Choosing the right IoT Hub tier.

    • Microsoft Defender for IoT: Turn this on to add an actress layer of threat protection to IoT and your devices. This option is not available for hubs in the gratuitous tier. Learn more about security recommendations for IoT Hub in Defender for IoT.

    • Role-based access control: Cull how access to the IoT hub is managed, whether shared access policies are allowed or only role-based access control is supported. For more information, see Control access to IoT Hub by using Azure Active Directory.

    • Device-to-cloud partitions: This holding relates the device-to-deject letters to the number of simultaneous readers of the messages. Most hubs demand only four partitions.

  7. Select Next: Tags to continue to the next screen.

    Tags are proper noun/value pairs. You can assign the aforementioned tag to multiple resource and resource groups to categorize resource and consolidate billing. In this document, you won't exist adding whatsoever tags. For more information, see Use tags to organize your Azure resources.

    Assign tags for the hub using the Azure portal.

  8. Select Side by side: Review + create to review your choices. You see something like to this screen, merely with the values you selected when creating the hub.

    Review information for creating the new hub.

  9. Select Create to start the deployment of your new hub. Your deployment volition be in progress a few minutes while the hub is being created. Once the deployment is consummate, select Go to resource to open the new hub.

Register a new device in the IoT hub

In this section, you lot create a device identity in the identity registry in your IoT hub. A device cannot connect to a hub unless information technology has an entry in the identity registry. For more information, see the IoT Hub developer guide.

  1. In your IoT hub navigation menu, open up Devices, then select Add together Device to add a device in your IoT hub.

    Screen capture that shows how to create a device identity in the portal

  2. In Create a device, provide a proper noun for your new device, such as myDeviceId, and select Save. This activeness creates a device identity for your IoT hub. Go out Auto-generate keys checked so that the primary and secondary keys will be generated automatically.

    Screen capture that shows how to add a new device

    Of import

    The device ID may be visible in the logs collected for customer support and troubleshooting, so make sure to avoid any sensitive data while naming it.

  3. After the device is created, open the device from the list in the Devices pane. Copy the Chief Connectedness String. This connection string is used by device code to communicate with the hub.

    By default, the keys and connexion strings are masked as they are sensitive information. If you click the center icon, they are revealed. It is not necessary to reveal them to copy them with the copy button.

    Screen capture that shows the device connection string

Note

The IoT Hub identity registry only stores device identities to enable secure access to the IoT hub. It stores device IDs and keys to use every bit security credentials, and an enabled/disabled flag that you can use to disable admission for an individual device. If your awarding needs to store other device-specific metadata, it should use an application-specific store. For more information, see IoT Hub developer guide.

Acquaintance an Azure Storage account to IoT Hub

To upload files from a device, you must have an Azure Storage account and Azure Blob Storage container associated with your IoT hub. In one case you associate the storage account and container with your IoT hub, your IoT hub tin provide the elements of a SAS URI when requested by a device. The device can then apply these elements to construct the SAS URI that it uses to authenticate with Azure Storage and upload files to the blob container.

To associate an Azure Storage account with your IoT hub:

  1. Nether Hub settings, select File upload on the left-pane of your IoT hub.

    Screen capture showing select file upload settings from the portal.

  2. On the File upload pane, select Azure Storage Container. For this article, information technology'southward recommended that your storage business relationship and IoT Hub be located in the same region.

    • If you lot already take a storage business relationship yous want to use, select information technology from the listing.

    • To create a new storage business relationship, select +Storage account. Provide a name for the storage business relationship and make sure the Location is set to the same region equally your IoT hub, then select OK. The new account is created in the aforementioned resource group as your IoT hub. When the deployment completes, select the storage account from the list.

    Later on yous select the storage account, the Containers pane opens.

  3. On the Containers pane, select the blob container.

    • If you already have a blob container y'all want to use, select it from the list and click Select.

    • To create a new blob container, select + Container. Provide a proper noun for the new container. For the purposes of this article, you can leave all other fields at their default. Select Create. When the deployment completes, select the container from the list and click Select.

  4. Back on the File upload pane, brand sure that file notifications are set to On. You can leave all other settings at their defaults. Select Save and wait for the settings to consummate before moving on to the adjacent section.

    Screen capture showing confirm file upload settings in the portal.

For more detailed instructions on how to create an Azure Storage account, see Create a storage business relationship. For more detailed instructions on how to associate a storage account and blob container with an IoT hub, encounter Configure file uploads using the Azure portal.

Upload file from a device app

In this article, you'll use a sample from the Azure IoT C# samples repository you downloaded before every bit the device app. Yous can open up the files below using Visual Studio, Visual Studio Code, or a text editor of your choice.

The sample is located in the azure-iot-samples-csharp-master\iot-hub\Samples\device\FileUploadSample under the binder where you lot extracted the Azure IoT C# samples.

Examine the code in FileUpLoadSample.cs. This file contains the master sample logic. After creating an IoT Hub device client, information technology follows the standard three-role procedure for uploading files from a device:

  1. The code calls the GetFileUploadSasUriAsync method on the device client to get a SAS URI from the IoT hub:

                      var fileUploadSasUriRequest = new FileUploadSasUriRequest {     BlobName = fileName };  // Lines removed for clarity  FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest); Uri uploadUri = sasUri.GetBlobUri();

  2. The code uses the SAS URI to upload the file to Azure storage. In this sample, it uses the SAS URI to create an Azure storage block blob client and uploads the file:

                      var blockBlobClient = new BlockBlobClient(uploadUri); await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());

  3. The code notifies the IoT hub that it has completed the upload. This tells the IoT hub that it can release resources associated with the upload (the SAS URI). If file upload notifications are enabled, the IoT hub volition send a notification message to backend services.

                      var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification {     // Mandatory. Must be the aforementioned value as the correlation id returned in the sas uri response     CorrelationId = sasUri.CorrelationId,      // Mandatory. Will be present when service client receives this file upload notification     IsSuccess = truthful,      // Optional, user defined condition code. Will be nowadays when service client receives this file upload notification     StatusCode = 200,      // Optional, user-divers status clarification. Will exist nowadays when service client receives this file upload notification     StatusDescription = "Success" };  await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

If you examine the parameter.cs file, you'll meet that:

  • The sample requires y'all to pass a parameter, p, which takes a device connexion string.

  • By default, the device sample uses the MQTT protocol to communicate with IoT Hub. You tin use the parameter t to change this ship protocol. Be aware that, regardless of this selection, the Azure blob client always uses HTTPS every bit the protocol to upload the file Azure storage.

Get the IoT hub connection string

In this commodity, you lot create a backend service to receive file upload notification letters from your IoT hub. To receive file upload notification messages, your service needs the service connect permission. By default, every IoT Hub is created with a shared access policy named service that grants this permission.

To become the IoT Hub connection string for the service policy, follow these steps:

  1. In the Azure portal, select Resources groups. Select the resource group where your hub is located, so select your hub from the list of resource.

  2. On the left-side pane of your IoT hub, select Shared admission policies.

  3. From the listing of policies, select the service policy.

  4. Nether Shared admission keys, select the copy icon for the Primary connectedness cord and save the value.

Screenshot that shows how to retrieve the connection string

For more than information about IoT Hub shared access policies and permissions, meet Admission control and permissions.

Receive a file upload notification

In this department, you create a C# console app that receives file upload notification messages from your IoT hub.

  1. Open a command window and go to the folder where you want to create the project. Create a folder named ReadFileUploadNotifications and change directories to that binder.

                      mkdir ReadFileUploadNotification cd ReadFileUploadNotification

  2. Run the following command to create a C# console project. After running the command, the folder will comprise a Program.cs file and a ReadFileUploadNotification.csproj file.

                      dotnet new console --linguistic communication c#

  3. Run the following command to add the Microsoft.Azure.Devices package to the project file. This package is the Azure IoT .NET service SDK.

                      dotnet add together package Microsoft.Azure.Devices

  4. Open the Program.cs file and add the following statement at the top of the file:

                      using Microsoft.Azure.Devices;

  5. Add together the following fields to the Programme class. Replace the {iot hub connexion string} placeholder value with the IoT hub connection string that y'all copied previously in Get the IoT hub connection string:

                      static ServiceClient serviceClient; static string connectionString = "{iot hub connexion string}";

  6. Add the following method to the Program grade:

                      private async static void ReceiveFileUploadNotificationAsync() {     var notificationReceiver = serviceClient.GetFileNotificationReceiver();     Console.WriteLine("\nReceiving file upload notification from service");     while (true)     {         var fileUploadNotification = await notificationReceiver.ReceiveAsync();         if (fileUploadNotification == zippo) go along;         Console.ForegroundColor = ConsoleColor.Yellow;         Console.WriteLine("Received file upload notification: {0}",            string.Bring together(", ", fileUploadNotification.BlobName));         Panel.ResetColor();         await notificationReceiver.CompleteAsync(fileUploadNotification);     } }

    Note this receive pattern is the aforementioned ane used to receive deject-to-device letters from the device app.

  7. Finally, supersede the lines in the Main method with the following:

                      Console.WriteLine("Receive file upload notifications\n"); serviceClient = ServiceClient.CreateFromConnectionString(connectionString); ReceiveFileUploadNotificationAsync(); Console.WriteLine("Press Enter to exit\due north"); Console.ReadLine();

Run the applications

Now you're fix to run the applications.

  1. First, run the service app to receive file upload notifications from the IoT hub. At your command prompt in the ReadFileUploadNotification folder, run the following commands:

                      dotnet restore dotnet run

    The app starts and waits for a file upload notification from your IoT hub:

                      Receive file upload notifications   Receiving file upload notification from service Press Enter to leave

  2. Next, run the device app to upload the file to Azure storage. Open a new command prompt and alter folders to the azure-iot-samples-csharp-master\iot-hub\Samples\device\FileUploadSample under the binder where you expanded the Azure IoT C# samples. Run the following commands. Replace the {Your device connection string} placeholder value in the second control with the device connection string you copied previously in Register a new device in the IoT hub.

                      dotnet restore dotnet run --p "{Your device connectedness string}"

    The following output is from the device app after the upload has completed:

                                          Uploading file TestPayload.txt   Getting SAS URI from IoT Hub to use when uploading the file...   Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub   Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication   Successfully uploaded the file to Azure Storage   Notified IoT Hub that the file upload succeeded and that the SAS URI tin can exist freed.   Time to upload file: 00:00:01.5077954.   Done.

  3. Detect that the service app shows that it has received the file upload notification:

                      Receive file upload notifications   Receiving file upload notification from service Press Enter to exit  Received file upload notification: myDeviceId/TestPayload.txt

Verify the file upload

You can use the portal to view the uploaded file in the storage container you configured:

  1. Navigate to your storage account in Azure portal.

  2. On the left pane of your storage account, select Containers.

  3. Select the container you uploaded the file to.

  4. Select the binder named after your device.

  5. Select the blob that yous uploaded your file to. In this article, it's the hulk named TestPayload.txt.

    Screenshot of selecting the uploaded file in the Azure portal.

  6. View the blob properties on the page that opens. You can select Download to download the file and view its contents locally.

Next steps

In this tutorial, you learned how to use the file upload feature of IoT Hub to simplify file uploads from devices. You can go on to explore this characteristic with the following articles:

  • Overview of file uploads with IoT Hub

  • Configure IoT Hub file uploads

  • Azure blob storage documentation

  • Azure blob storage API reference

  • Azure IoT SDKs