Use Visual Studio 2022 to develop and debug modules for Azure IoT Edge

1. In the Solution Explorer, right-click the name of your main project and select Set IoT Edge runtime version.

   

2. Use the drop-down menu to choose the runtime version that your IoT Edge devices are running, then select OK to save your changes. If no change was made, select Cancel to exit.

   Currently, the extension doesn't include a selection for the latest runtime versions. If you want to set the runtime version higher than 1.2, open deployment.debug.template.json deployment manifest file. Change the runtime version for the system runtime module images edgeAgent and edgeHub. For example, if you want to use the IoT Edge runtime version 1.5, change the following lines in the deployment manifest file:

   "systemModules": {
      "edgeAgent": {
       //...
         "image": "mcr.microsoft.com/azureiotedge-agent:1.5"
       //...
      "edgeHub": {
      //...
         "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
      //...
   

3. If you changed the version, regenerate your deployment manifest by right-clicking the name of your project and select Generate deployment for IoT Edge. This generates a deployment manifest based on your deployment template and appears in the config folder of your Visual Studio project.

1. Open deployment.debug.template.json deployment manifest file. The deployment manifest is a JSON document that describes the modules to be configured on the targeted IoT Edge device.

2. Change the runtime version for the system runtime module images edgeAgent and edgeHub. For example, if you want to use the IoT Edge runtime version 1.5, change the following lines in the deployment manifest file:

   "systemModules": {
       "edgeAgent": {
       //...
           "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
       //...
       "edgeHub": {
       //...
           "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
       //...
   

Debug using the simulator

The Azure IoT EdgeHub Dev Tool provides a local development and debug experience. The tool helps start IoT Edge modules without the IoT Edge runtime so that you can create, develop, test, run, and debug IoT Edge modules and solutions locally. You don't have to push images to a container registry and deploy them to a device for testing.

For more information, see Azure IoT EdgeHub Dev Tool.

To initialize the tool in Visual Studio:

1. Retrieve the connection string of your IoT Edge device (found in your IoT Hub) from the Azure portal or from the Azure CLI.

   If using the CLI to retrieve your connection string, use this command, replacing "[device_id]" and "[hub_name]" with your own values:

   az iot hub device-identity connection-string show --device-id [device_id] --hub-name [hub_name]
   

2. From the Tools menu in Visual Studio, select Azure IoT Edge Tools > Setup IoT Edge Simulator.

3. Paste the connection string and select OK.

Build and debug a single module

Typically, you want to test and debug each module before running it within an entire solution with multiple modules. The IoT Edge simulator tool allows you to run a single module in isolation a send messages over port 53000.

1. In Solution Explorer, select and highlight the module project folder (for example, IotEdgeModule1). Set the custom module as the startup project. Select Project > Set as StartUp Project from the menu.

2. Press F5 or select the run toolbar button to start the IoT Edge simulator for a single module. It may take 10 to 20 seconds the initially.

   

3. You should see a .NET Core console app window appear if the module has been initialized successfully.

4. Set a breakpoint to inspect the module.

   • If developing in C#, set a breakpoint in the PipeMessage() function in ModuleBackgroundService.cs.
   • If using C, set a breakpoint in the InputQueue1Callback() function in main.c.

5. Test the module by sending a message. When you're debugging a single module, the simulator listens on the default port 53000 for messages. To send a message to your module, run the following curl command from a command shell like Git Bash or WSL Bash.

   curl --header "Content-Type: application/json" --request POST --data '{"inputName": "input1","data":"hello world"}' http://localhost:53000/api/v1/messages
   

   If you get the error unmatched close brace/bracket in URL, try the following command instead:

   curl --header "Content-Type: application/json" --request POST --data "{\"inputName\": \"input1\", \"data\", \"hello world\"}"  http://localhost:53000/api/v1/messages
   

   

   The breakpoint should be triggered. You can watch variables in the Visual Studio Locals window, found when the debugger is running. Go to Debug > Windows > Locals.

   In your Bash or shell, you should see a {"message":"accepted"} confirmation.

   In your .NET console you should see:

   IoT Hub module client initialized.
   Received message: 1, Body: [hello world]
   

6. Press Ctrl + F5 or select the stop button to stop debugging.

Build and debug multiple modules

After you're done developing a single module, you might want to run and debug an entire solution with multiple modules. The IoT Edge simulator tool allows you to run all modules defined in the deployment manifest including a simulated edgeHub for message routing. In this example, you run two custom modules and the simulated temperature sensor module. Messages from the simulated temperature sensor module are routed to each custom module.

1. In Solution Explorer, add a second module to the solution by right-clicking the main project folder. On the menu, select Add > New IoT Edge Module.

   

2. In the Add module window give your new module a name and replace the localhost:5000 portion of the repository URL with your Azure Container Registry login server, like you did before.

3. Open the file deployment.debug.template.json to see that the new module has been added in the modules section. A new route was also added to the routes section in EdgeHub to send messages from the new module to IoT Hub. To send data from the simulated temperature sensor to the new module, add another route with the following line of JSON. Replace <NewModuleName> (in two places) with your own module name.

   "sensorTo<NewModuleName>": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/<NewModuleName>/inputs/input1\")"
   

4. Right-click the main project (for example, AzureIotEdgeApp1) and select Set as StartUp Project. By setting the main project as the startup project, all modules in the solution run. This includes both modules you added to the solution, the simulated temperature sensor module, and the simulated Edge hub.

5. Press F5 or select the run toolbar button to run the solution. It may take 10 to 20 seconds initially. Be sure you don't have other Docker containers running that might bind the port you need for this project.

6. You should see two .NET Core console app windows appear one for each module.

7. Set a breakpoint to inspect the modules.

   • If developing in C#, set a breakpoint in the PipeMessage() function in ModuleBackgroundService.cs.
   • If using C, set a breakpoint in the InputQueue1Callback() function in main.c.

8. Create breakpoints in each module and then press F5 to run and debug multiple modules simultaneously. You should see multiple .NET Core console app windows, with each window representing a different module.

   

9. Press Ctrl + F5 or select the stop button to stop debugging.

Build and push images to registry

Once you've developed and debugged your module, you can build and push the module image to your Azure Container Registry. You can then deploy the module to your IoT Edge device.

1. Set the main IoT Edge project as the start-up project, not one of the individual modules.

2. Select either Debug or Release as the configuration to build for your module images.

   Note

   When choosing Debug, Visual Studio uses Dockerfile.(amd64|windows-amd64).debug to build Docker images. This includes the .NET Core command-line debugger VSDBG in your container image while building it. For production-ready IoT Edge modules, we recommend that you use the Release configuration, which uses Dockerfile.(amd64|windows-amd64) without VSDBG.

3. If you're using a private registry like Azure Container Registry (ACR), use the following Docker command to sign in to it. You can get the username and password from the Access keys page of your registry in the Azure portal.

   docker login azure --cloud-name AzureChinaCloud <ACR login server>
   

4. Let's add the Azure Container Registry login information to the runtime settings found in the file deployment.debug.template.json. There are two ways to do this. You can either add your registry credentials to your .env file (most secure) or add them directly to your deployment.debug.template.json file.

   Add credentials to your .env file:

   In Solution Explorer, select the Show All Files toolbar button. The .env file appears. Add your Azure Container Registry username and password to your .env file. These credentials can be found on the Access Keys page of your Azure Container Registry in the Azure portal.

   

       DEFAULT_RT_IMAGE=1.2
       CONTAINER_REGISTRY_USERNAME_myregistry=<my-registry-name>
       CONTAINER_REGISTRY_PASSWORD_myregistry=<my-registry-password>
   

   Add credentials directly to deployment.debug.template.json

   If you'd rather add your credentials directly to your deployment template, replace the placeholders with your ACR admin username, password, and registry name.

         "settings": {
           "minDockerVersion": "v1.25",
           "loggingOptions": "",
           "registryCredentials": {
             "registry1": {
               "username": "<username>",
               "password": "<password>",
               "address": "<registry name>.azurecr.cn"
             }
           }
         }
   

   Note

   This article uses admin login credentials for Azure Container Registry, which are convenient for development and test scenarios. When you're ready for production scenarios, we recommend a least-privilege authentication option like service principals. For more information, see Manage access to your container registry.

5. If you're using a local registry, you can run a local registry.

6. Finally, in the Solution Explorer, right-click the main project folder and select Build and Push IoT Edge Modules to build and push the Docker image for each module. This might take a minute. When you see Finished Build and Push IoT Edge Modules. in your Output console of Visual Studio, you're done.

Deploy the solution

Now that you've built and pushed your module images to your Azure Container Registry, you can deploy the solution to your IoT Edge device. You already have a deployment manifest template you've been observing throughout this tutorial. Let's generate a deployment manifest from that, then use an Azure CLI command to deploy your modules to your IoT Edge device in Azure.

1. Right-click on your main project in Visual Studio Solution Explorer and choose Generate Deployment for IoT Edge.

   

2. Go to your local Visual Studio main project folder and look in the config folder. The file path might look like this: C:\Users\<YOUR-USER-NAME>\source\repos\<YOUR-IOT-EDGE-PROJECT-NAME>\config. Here you find the generated deployment manifest such as deployment.amd64.debug.json.

3. Check your deployment.amd64.debug.json file to confirm the edgeHub schema version is set to 1.2.

    "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.2",
          "routes": {
            "IotEdgeModule2022ToIoTHub": "FROM /messages/modules/IotEdgeModule2022/outputs/* INTO $upstream",
            "sensorToIotEdgeModule2022": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/IotEdgeModule2022/inputs/input1\")",
            "IotEdgeModule2022bToIoTHub": "FROM /messages/modules/IotEdgeModule2022b/outputs/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      }
   

   Tip

   The deployment template for Visual Studio 2022 requires the 1.2 schema version. If you need it to be 1.1 or 1.0, wait until after the deployment is generated (do not change it in deployment.debug.template.json). Generating a deployment will create a 1.2 schema by default. However, you can manually change deployment.amd64.debug.json, the generated manifest, if needed before deploying it to Azure.

   Important

   Once your IoT Edge device is deployed, it currently won't display correctly in the Azure portal with schema version 1.2 (version 1.1 will be fine). This is a known bug and will be fixed soon. However, this won't affect your device, as it's still connected in IoT Hub and can be communicated with at any time using the Azure CLI.

   

4. Now let's deploy our manifest with an Azure CLI command. Open the Visual Studio Developer Command Prompt and change to the config directory.

       cd config
   

5. Deploy the manifest for your IoT Edge device to IoT Hub. The command configures the device to use modules developed in your solution. The deployment manifest was created in the previous step and stored in the config folder. From your config folder, execute the following deployment command. Replace the [device id], [hub name], and [file path] with your values. If the IoT Edge device ID doesn't exist in the IoT Hub, it must be created.

       az iot edge set-modules --device-id [device id] --hub-name [hub name] --content [file path]
   

   For example, your command might look like this:

   az iot edge set-modules --device-id my-device-name --hub-name my-iot-hub-name --content deployment.amd64.debug.json
   

6. After running the command, you'll see a confirmation of deployment printed in JSON in your command prompt.

Build module Docker image

Once you've developed your module, you can build the module image to store in a container registry for deployment to your IoT Edge device.

Use the module's Dockerfile to build the module Docker image.

docker build --rm -f "<DockerFilePath>" -t <ImageNameAndTag> "<ContextPath>" 

For example, let's assume your command shell is in your project directory and your module name is IotEdgeModule1. To build the image for the local registry or an Azure container registry, use the following commands:

# Build the image for the local registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t localhost:5000/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Or build the image for an Azure Container Registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t myacr.azurecr.cn/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

Push module Docker image

Push your module image to the local registry or a container registry.

docker push <ImageName>

For example:

# Push the Docker image to the local registry

docker push localhost:5000/iotedgemodule1:0.0.1-amd64

# Or push the Docker image to an Azure Container Registry
az acr login --name myacr
docker push myacr.azurecr.cn/iotedgemodule1:0.0.1-amd64

Deploy the module to the IoT Edge device.

In Visual Studio, open deployment.debug.template.json deployment manifest file in the main project. The deployment manifest is a JSON document that describes the modules to be configured on the targeted IoT Edge device. Before deployment, you need to update your Azure Container Registry credentials, your module images, and the proper createOptions values. For more information about createOption values, see How to configure container create options for IoT Edge modules.

1. If you're using an Azure Container Registry to store your module image, you need to add your credentials to deployment.debug.template.json in the edgeAgent settings. For example,

   "modulesContent": {
   "$edgeAgent": {
     "properties.desired": {
       "schemaVersion": "1.1",
       "runtime": {
         "type": "docker",
         "settings": {
           "minDockerVersion": "v1.25",
           "loggingOptions": "",
           "registryCredentials": {
             "myacr": {
               "username": "myacr",
               "password": "<your_acr_password>",
               "address": "myacr.azurecr.cn"
             }
           }
         }
       },
   //...
   

2. Replace the image property value with the module image name you pushed to the registry. For example, if you pushed an image tagged myacr.azurecr.cn/iotedgemodule1:0.0.1-amd64 for custom module IotEdgeModule1, replace the image property value with the tag value.

3. Add or replace the createOptions value with stringified content for each system and custom module in the deployment template.

   For example, the IotEdgeModule1's image and createOptions settings would be similar to the following:

   "IotEdgeModule1": {
   "version": "1.0.0",
   "type": "docker",
   "status": "running",
   "restartPolicy": "always",
   "settings": {
       "image": "myacr.azurecr.cn/iotedgemodule1:0.0.1-amd64",
       "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
   }
   

Use the IoT Edge Azure CLI set-modules command to deploy the modules to the Azure IoT Hub. For example, to deploy the modules defined in the deployment.debug.amd64.json file to IoT Hub my-iot-hub for the IoT Edge device my-device, use the following command:

az iot edge set-modules --hub-name my-iot-hub --device-id my-device --content ./deployment.debug.template.json --login "HostName=my-iot-hub.azure-devices.cn;SharedAccessKeyName=iothubowner;SharedAccessKey=<SharedAccessKey>"