Debug IoT Edge C / C# Windows Module Container with Visual Studio Azure IoT Edge Tools

Renlong Tu

Azure IoT Edge Tools (Preview) for Visual Studio 2017 allows you to easily develop and debug Azure IoT Edge modules locally. To learn how to use this extension to develop and debug Edge module locally, you can refer these documents:

Easily Develop and Debug Azure IoT Edge C Modules with Azure IoT Edge Tools

Use Visual Studio 2017 to develop and debug modules for Azure IoT Edge (Preview)

However, remote debugging module container running in Edge device is not straightforward. This tutorial will demonstrate how to remotely debug C / C# Windows module container from your dev machine.

For Linux and ARM platform, you can refer this blog:

Debug IoT Edge C / C# Linux Module Container with Visual Studio Azure IoT Edge Tools

Let’s see how it works.


Setup Your Remote Windows Machine as an IoT Edge Device

  • Set up your remote Windows machine as an IoT Edge device – follow this instruction to install Azure IoT Edge Runtime on Windows
  • Configure the Windows Firewall to enable 4022 port which will be used by remote debugger

Setup Your Development Machine

  • OS: Windows 10 with 1809 update
  • Visual Studio 2017 with update 7 or later, including workloads “.NET desktop development”, “Windows desktop development with C++” and “Azure development workload”;
  • Download and install Azure IoT Edge Tools (Preview) for Visual Studio
  • You may either use container engine Moby or Docker Desktop for Windows
  • To use container engine Moby, first follow IoT Edge quickstart to install Moby, then search and click edit system environment variables in Control Panel, then add environment variable DOCKER_HOST=npipe:////./pipe/iotedge_moby_engine Please note you should restart Visual Studio after editing environment variables to make the change taking effect.
  • To use Docker Desktop for Windows, download and install Docker Desktop for Windows.
  • Set up your local development environment to debug, run, and test your IoT Edge solution by installing the Azure IoT EdgeHub Dev Tool. Install Python (2.7/3.6) and Pip and then install the iotedgehubdev package by running the following command in your terminal. Make sure your Azure IoT EdgeHub Dev Tool version is equal or greater than 0.8.0.
    pip install --upgrade iotedgehubdev
  • Install azure-iot-sdk-c for windows-x64 through vcpkg
    git clone
    cd vcpkg
    .\vcpkg install azure-iot-sdk-c:x64-windows
    .\vcpkg --triplet x64-windows integrate install

Switch to Windows Containers

  • This doc will use windows containers to demonstrate how to debug C# / C modules using Windows IoT Edge project (which ending with Windows.Amd64 by default).
    • If you’re using container engine Moby, then you can just go to the next section and do not need to switch.
    • If you’re using Docker desktop for Windows, you need to switch to Windows containers.

Debug C / C# Module Container Running in Remote Edge Device

  1. Run Visual Studio as administrator, select New > Project from the File menu.
  2. Open Visual Studio 2017 and click menu File -> New ->Project. In the New Project dialog, select Installed -> Azure IoT, select Azure IoT Edge (Windows amd64), enter a name for your project and specify the location, and then select OK.
  3. In the project wizard, select C or C# Module, and replace localhost:5000 with your own registry info, then click Yes:Now there’re two projects in the solution, one is Edge module project, which is just simple .Net Core or C project, the other one is called Edge project. To debug C / C# module in windows container, we need to add another docker file to the IoTEdgeModule1 project, and you can find the docker file below:

    For C module, add a file as below : Dockerfile for Azure IoT Edge Windows C Module with Remote Debug Support

    For C# module, add a file as below: Dockerfile for Azure IoT Edge Windows C# Module with Remote Debug Support

    The docker file will add VS remote debugger binaries to the container which will be used for remote debugger.

  4. We also need to add a helper script BuildAndPush.cmd in the IoTEdgeModule1 project to collect remote debugger binaries from your development machine, and then build and push module image.For C module, you can copy the script file here: Build and Push Image Script for C Windows ModuleFor C# module, you can copy the script file here: Build and Push Image Script for C# Windows Module

    Don’t forget to update the script to push image to your own repository

    echo Push image...
    docker tag %DockerImageName% [Your Registry Server]/%DockerImageName%
    docker push [Your Registry Server]/%DockerImageName%
  5. Update module.json to make sure AzureIoTEdgeApp1 project can find file.

  6. Edit module IoTEdgeModule1 in deployment.template.json file to expose 4022 port
          "createOptions":"{\"ExposedPorts\":{\"4022/tcp\": {}}, \"HostConfig\":{\"PortBindings\":{\"4022/tcp\":[{\"HostPort\":\"4022\"}]}}}"
  7. Right click AzureIotEdgeApp1 project, click Properties and change the Target Configuration to Debug.
  8. If you’re using private registry like Azure Container Registry, use the following Docker command to sign in.
    docker login -u <ACR username> -p <ACR password> <ACR login server>


  9. Click Show All Files icon as below, a .env file should be displayed under Edge project, open the .env file to input credential for your registry, this credential will be used by IoT Edge runtime to pull module images after deployment.
  10. Right click AzureIotEdgeApp1 project, and click Generate Deployment for IoT Edge to generate deployment manifest
  11. Open Developer Command Prompt for VS2017 (NOT Command Prompt) with Administrator privilege, locate to the folder of IoTEdgeModule1 and run BuildAndPush.cmd script to build and push your image.
  12. After successfully pushing the image, open Cloud Explorer by clicking View -> Cloud Explorer, expand your subscription and find the IoT Edge device corresponding to your Windows device, right click on the IoT Edge device to create a deployment for it, you need to select the deployment manifest file under the path below:

  13. Login to remote Windows machine and manually start the msvsmon.exe in the container using the command below:
    docker exec -it -d [Your Edge Module Container ID] msvsmon.exe /fallbackloadremotemanagedpdbs /noauth /anyuser /silent /nostatus /noclrwarn /nosecuritywarn /nofirewallwarn /nowowwarn /timeout:360000
  14. After successfully starting remote debugger, click Debug->Attach to Process…, set Connection Type to Remote (no authentication)Connection target to [IP Address]:4022, and type Enter then you can choose the process to debug. For C module, you need to choose process IoTEdgeModule1.exe and “Attach to” to Native code. For C# module you need to choose process dotnet.exe and “Attach to” to Managed (CoreCLR).
  15. Now you can set break point and debug your C / C# module

Samples Projects

Azure IoT Edge C Windows remote debug sample:

Azure IoT Edge C# Windows remote debug sample:



Discussion is closed. Login to edit/delete existing comments.

Feedback usabilla icon