使用 Visual Studio Code 开发和调试 Azure IoT Edge 模块Use Visual Studio Code to develop and debug modules for Azure IoT Edge

可以将业务逻辑转变为用于 Azure IoT Edge 的模块。You can turn your business logic into modules for Azure IoT Edge. 本文展示了如何使用 Visual Studio Code 作为主要工具来开发和调试模块。This article shows you how to use Visual Studio Code as the main tool to develop and debug modules.

可以使用两种方式在 Visual Studio Code 中调试用 C#、Node.js 或 Java 编写的模块:可在模块容器中附加一个进程,或在调试模式下启动模块代码。There are two ways to debug modules written in C#, Node.js, or Java in Visual Studio Code: You can either attach a process in a module container or launch the module code in debug mode. 若要调试用 Python 或 C 编写的模块,只能将其附加到 Linux amd64 容器中的进程。To debug modules written in Python or C, you can only attach to a process in Linux amd64 containers.

如果你不熟悉 Visual Studio Code 的调试功能,请阅读有关Debugging(调试)的信息。If you aren't familiar with the debugging capabilities of Visual Studio Code, read about Debugging.

本文说明了如何以多种语言为多种体系结构开发和调试模块。This article provides instructions for developing and debugging modules in multiple languages for multiple architectures. 目前,Visual Studio Code 为用 C#、C、Python、Node.js 和 Java 编写的模块提供支持。Currently, Visual Studio Code provides support for modules written in C#, C, Python, Node.js, and Java. 支持的设备体系结构为 X64 和 ARM32。The supported device architectures are X64 and ARM32. 有关支持的操作系统、语言和体系结构的详细信息,请参阅语言和体系结构支持For more information about supported operating systems, languages, and architectures, see Language and architecture support.

先决条件Prerequisites

可以使用运行 Windows、macOS 或 Linux 的计算机或虚拟机作为开发计算机。You can use a computer or a virtual machine running Windows, macOS, or Linux as your development machine. 在 Windows 计算机上,可以开发 Windows 或 Linux 模块。On Windows computers you can develop either Windows or Linux modules. 若要开发 Windows 模块,请使用运行版本 1809/内部版本 17763 或更高版本的 Windows 计算机。To develop Windows modules, use a Windows computer running version 1809/build 17763 or newer. 若要开发 Linux 模块,请使用符合 Docker Desktop 要求的 Windows 计算机。To develop Linux modules, use a Windows computer that meets the requirements for Docker Desktop.

首先安装 Visual Studio Code,然后添加以下扩展:Install Visual Studio Code first and then add the following extensions:

此外还需要安装一些其他特定于语言的工具来开发模块:You'll also need to install some additional, language-specific tools to develop your module:

若要生成并部署模块映像,需使用 Docker 生成模块映像,并使用容器注册表来保存模块映像:To build and deploy your module image, you need Docker to build the module image and a container registry to hold the module image:

除非使用 C 开发模块,否则还需要基于 Python 的 Azure IoT EdgeHub 开发工具,以便设置本地开发环境以调试、运行和测试 IoT Edge 解决方案。Unless you're developing your module in C, you also need the Python-based Azure IoT EdgeHub Dev Tool in order to set up your local development environment to debug, run, and test your IoT Edge solution. 如果尚未这样做,请安装 Python (2.7/3.6/3.7) 和 Pip,然后在终端中运行此命令安装“iotedgehubdev” 。If you haven't already done so, install Python (2.7/3.6/3.7) and Pip and then install iotedgehubdev by running this command in your terminal.

pip install --upgrade iotedgehubdev

备注

目前,iotedgehubdev 使用与 Python 3.8 不兼容的 docker-py 库。Currently, iotedgehubdev uses a docker-py library that is not compatible with Python 3.8.

如果有多个 Python,包括预安装的 python 2.7(例如,在 Ubuntu 或 macOS 上),请确保使用正确的 pippip3 来安装 iotedgehubdevIf you have multiple Python including pre-installed python 2.7 (for example, on Ubuntu or macOS), make sure you are using the correct pip or pip3 to install iotedgehubdev

若要在设备上测试模块,至少需要一个 IoT Edge 设备和一个活动的 IoT 中心。To test your module on a device, you'll need an active IoT hub with at least one IoT Edge device. 若要将计算机用作 IoT Edge 设备,请按照 LinuxWindows 快速入门中的步骤进行操作。To use your computer as an IoT Edge device, follow the steps in the quickstart for Linux or Windows. 如果正在开发计算机上运行 IoT Edge 守护程序,则可能需要先停止 EdgeHub 和 EdgeAgent,然后再继续下一步。If you are running IoT Edge daemon on your development machine, you might need to stop EdgeHub and EdgeAgent before you move to next step.

创建新的解决方案模板Create a new solution template

以下步骤说明如何使用 Visual Studio Code 和 Azure IoT Tools 以首选开发语言(包括使用 C# 编写的 Azure Functions)创建 IoT Edge 模块。The following steps show you how to create an IoT Edge module in your preferred development language (including Azure Functions, written in C#) using Visual Studio Code and the Azure IoT Tools. 首先创建一个解决方案,然后生成该解决方案中的第一个模块。You start by creating a solution, and then generating the first module in that solution. 每个解决方案可以包含多个模块。Each solution can contain multiple modules.

  1. 选择“查看” > “命令面板” 。Select View > Command Palette.

  2. 在“命令面板”中,输入并运行 Azure IoT Edge: New IoT Edge Solution 命令。In the command palette, enter and run the command Azure IoT Edge: New IoT Edge Solution.

    运行新的 IoT Edge 解决方案

  3. 浏览到要在其中创建新解决方案的文件夹,然后选择“选择文件夹” 。Browse to the folder where you want to create the new solution and then select Select folder.

  4. 输入解决方案的名称。Enter a name for your solution.

  5. 选择首选开发语言的模块模板作为解决方案中的第一个模块。Select a module template for your preferred development language to be the first module in the solution.

  6. 输入模块的名称。Enter a name for your module. 选择容器注册表中唯一的名称。Choose a name that's unique within your container registry.

  7. 提供模块的映像存储库的名称。Provide the name of the module's image repository. Visual Studio Code 使用“localhost:5000/<你的模块名称>”自动填充模块名 。Visual Studio Code autopopulates the module name with localhost:5000/<your module name>. 将其替换为你自己的注册表信息。Replace it with your own registry information. 如果使用本地 Docker 注册表进行测试,则可以使用 localhost 。If you use a local Docker registry for testing, then localhost is fine. 如果使用 Azure 容器注册表,那么请从注册表的设置中使用登录服务器。If you use Azure Container Registry, then use the login server from your registry's settings. 登录服务器类似于 <registry name> .azurecr.cnThe login server looks like <registry name>.azurecr.cn. 仅替换字符串的 localhost:5000 部分,使最终结果类似于 <registry name>.azurecr.cn/ <your module name>Only replace the localhost:5000 part of the string so that the final result looks like <registry name>.azurecr.cn/<your module name>.

    提供 Docker 映像存储库

Visual Studio Code 采用你提供的信息,创建一个 IoT Edge 解决方案,然后在新窗口中加载它。Visual Studio Code takes the information you provided, creates an IoT Edge solution, and then loads it in a new window.

该解决方案中有四个项:There are four items within the solution:

  • 一个 .vscode 文件夹,包含调试配置 。A .vscode folder contains debug configurations.

  • 一个 modules 文件夹,包含每个模块的子文件夹 。A modules folder has subfolders for each module. 在每个模块的文件夹中有一个 module.json 文件,用于控制模块的构建和部署方式。Within the folder for each module there is a file, module.json, that controls how modules are built and deployed. 需修改此文件,将模块部署容器注册表从 localhost 更改为远程注册表。This file would need to be modified to change the module deployment container registry from localhost to a remote registry. 现在,只有一个模块。At this point, you only have one module. 但是可以在命令面板中使用以下命令添加更多模块:“Azure IoT Edge: Add IoT Edge Module”。But you can add more in the command palette with the command Azure IoT Edge: Add IoT Edge Module.

  • 一个 .env 文件,列出环境变量 。An .env file lists your environment variables. 如果 Azure 容器注册表是注册表,则其中将包含 Azure 容器注册表用户名和密码。If Azure Container Registry is your registry, you'll have an Azure Container Registry username and password in it.

    备注

    仅当为模块提供了映像存储库时,才会创建环境文件。The environment file is only created if you provide an image repository for the module. 如果接受 localhost 默认值在本地进行测试和调试,则不需要声明环境变量。If you accepted the localhost defaults to test and debug locally, then you don't need to declare environment variables.

  • 一个 deployment.template.json 文件,列出新模块以及模拟可用于测试的数据的示例 SimulatedTemperatureSensor 模块 。A deployment.template.json file lists your new module along with a sample SimulatedTemperatureSensor module that simulates data you can use for testing. 有关部署清单如何工作的详细信息,请参阅了解如何使用部署清单部署模块和建立路由For more information about how deployment manifests work, see Learn how to use deployment manifests to deploy modules and establish routes.

若要了解模拟温度模块的工作原理,请查看 SimulatedTemperatureSensor.csproj 源代码To see how the simulated temperature module works, view the SimulatedTemperatureSensor.csproj source code.

添加其他模块Add additional modules

若要向解决方案添加其他模块,请从命令面板运行命令“Azure IoT Edge: 添加 IoT Edge 模块”。To add additional modules to your solution, run the command Azure IoT Edge: Add IoT Edge Module from the command palette. 也可以右键单击 Visual Studio Code 资源管理器视图中的“模块”文件夹或 deployment.template.json 文件,然后选择“添加 IoT Edge 模块” 。You can also right-click the modules folder or the deployment.template.json file in the Visual Studio Code Explorer view and then select Add IoT Edge Module.

开发模块Develop your module

解决方案附带的默认 C# 模块代码位于以下位置:The default module code that comes with the solution is located at the following location:

  • Azure Function (C#):modules > <你的模块名称> > <你的模块名称>.cs Azure Function (C#): modules > <your module name> > <your module name>.cs
  • C#:modules > <你的模块名称> > Program.cs C#: modules > <your module name> > Program.cs
  • Python:modules > <你的模块名称> > main.py Python: modules > <your module name> > main.py
  • Node.js:modules > <你的模块名称> > app.js Node.js: modules > <your module name> > app.js
  • Java:modules > <你的模块名称> > src > main > java > com > edgemodulemodules > App.java Java: modules > <your module name> > src > main > java > com > edgemodulemodules > App.java
  • C:modules > <你的模块名称> > main.c C: modules > <your module name> > main.c

设置模块和 deployment.template.json 文件,以便可以生成解决方案,将其推送到容器注册表,然后部署到设备以开始测试而无需触及任何代码。The module and the deployment.template.json file are set up so that you can build the solution, push it to your container registry, and deploy it to a device to start testing without touching any code. 生成该模块仅为简单从源(在此示例中,为模拟数据的 SimulatedTemperatureSensor 模块)获取输入并通过管道将其传送到 IoT 中心。The module is built to simply take input from a source (in this case, the SimulatedTemperatureSensor module that simulates data) and pipe it to IoT Hub.

当你准备使用自己的代码自定义模板时,请使用 Azure IoT Hub SDK 生成模块,以满足 IoT 解决方案的关键需求(例如安全性、设备管理和可靠性)。When you're ready to customize the template with your own code, use the Azure IoT Hub SDKs to build modules that address the key needs for IoT solutions such as security, device management, and reliability.

调试没有容器的模块 (C#、Node.js、Java)Debug a module without a container (C#, Node.js, Java)

如果使用 C#、Node.js 或 Java 进行开发,则模块需要在默认模块代码中使用“ModuleClient”对象,以便它可以启动、运行和路由消息 。If you're developing in C#, Node.js, or Java, your module requires use of a ModuleClient object in the default module code so that it can start, run, and route messages. 还将使用默认输入通道“input1”在模块接收消息时执行操作 。You'll also use the default input channel input1 to take action when the module receives messages.

为 IoT Edge 解决方案设置 IoT Edge 模拟器Set up IoT Edge simulator for IoT Edge solution

在开发计算机上,可以启动 IoT Edge 模拟器(而不是安装 IoT Edge 安全守护程序)以运行 IoT Edge 解决方案。On your development machine, you can start an IoT Edge simulator instead of installing the IoT Edge security daemon so that you can run your IoT Edge solution.

  1. 在左侧的设备资源管理器中,右键单击 IoT Edge 设备 ID,然后选择“设置 IoT Edge 模拟器”以使用设备连接字符串启动模拟器 。In device explorer on the left side, right-click on your IoT Edge device ID, and then select Setup IoT Edge Simulator to start the simulator with the device connection string.
  2. 通过读取集成终端中的进度详细信息,可以看到 IoT Edge 模拟器已成功设置。You can see the IoT Edge Simulator has been successfully set up by reading the progress detail in the integrated terminal.

为单个模块应用设置 IoT Edge 模拟器Set up IoT Edge simulator for single module app

若要设置和启动模拟器,请从 Visual Studio Code 命令选项板运行命令“Azure IoT Edge: 启动单模块的 IoT Edge Hub 模拟器。To set up and start the simulator, run the command Azure IoT Edge: Start IoT Edge Hub Simulator for Single Module from the Visual Studio Code command palette. 出现提示时,使用默认模块代码中的值“input1”(或代码中的等效值)作为应用程序的输入名称 。When prompted, use the value input1 from the default module code (or the equivalent value from your code) as the input name for your application. 该命令触发“iotedgehubdev”CLI,然后启动 IoT Edge 模拟器并测试实用程序模块容器 。The command triggers the iotedgehubdev CLI and then starts the IoT Edge simulator and a testing utility module container. 如果模拟器已成功以单模块模式启动,则可以在集成终端中看到下面的输出。You can see the outputs below in the integrated terminal if the simulator has been started in single module mode successfully. 还可以看到 curl 命令以帮助发送消息。You can also see a curl command to help send message through. 稍后将使用它。You will use it later.

为单个模块应用设置 IoT Edge 模拟器

可以使用 Visual Studio Code 中的 Docker 资源管理视图来查看模块的运行状态。You can use the Docker Explorer view in Visual Studio Code to see the module's running status.

模拟器模块状态

edgeHubDev 容器是本地 IoT Edge 模拟器的核心。The edgeHubDev container is the core of the local IoT Edge simulator. 它可以在没有 IoT Edge 安全守护程序的情况下在开发计算机上运行,并为本机模块应用或模块容器提供环境设置。It can run on your development machine without the IoT Edge security daemon and provides environment settings for your native module app or module containers. “input”容器公开 REST API 以帮助将消息桥接到模块上的目标输入通道 。The input container exposes REST APIs to help bridge messages to the target input channel on your module.

在启动模式下调试模块Debug module in launch mode

  1. 根据开发语言的要求准备环境以进行调试,在模块中设置断点,并选择要使用的调试配置:Prepare your environment for debugging according to the requirements of your development language, set a breakpoint in your module, and select the debug configuration to use:

    • C#C#

      • 在 Visual Studio Code 集成终端中,将目录更改为“<你的模块名称>”文件夹,然后运行以下命令以构建 .NET Core 应用程序。In the Visual Studio Code integrated terminal, change the directory to the <your module name> folder, and then run the following command to build .NET Core application.

        dotnet build
        
      • 打开 Program.cs 文件并添加断点。Open the file Program.cs and add a breakpoint.

      • 通过选择“视图”>“调试”以导航到 Visual Studio Code 调试视图 。Navigate to the Visual Studio Code Debug view by selecting View > Debug. 从下拉列表中选择调试配置“<你的模块名称> 本地调试(.NET Core)” 。Select the debug configuration <your module name> Local Debug (.NET Core) from the dropdown.

        备注

        如果 .NET Core TargetFrameworklaunch.json 中的程序路径不一致,则需要手动更新 launch.json 中的程序路径以匹配 .csproj 文件中的 TargetFramework,以便 Visual Studio Code 可以成功启动此程序。If your .NET Core TargetFramework is not consistent with your program path in launch.json, you'll need to manually update the program path in launch.json to match the TargetFramework in your .csproj file so that Visual Studio Code can successfully launch this program.

    • Node.jsNode.js

      • 在 Visual Studio Code 集成终端中,将目录更改为“<你的模块名称>”文件夹,然后运行以下命令以安装节点包In the Visual Studio Code integrated terminal, change the directory to the <your module name> folder, and then run the following command to install Node packages

        npm install
        
      • 打开 app.js 文件并添加断点。Open the file app.js and add a breakpoint.

      • 通过选择“视图”>“调试”以导航到 Visual Studio Code 调试视图 。Navigate to the Visual Studio Code Debug view by selecting View > Debug. 从下拉列表中选择调试配置“<你的模块名称> 本地调试(Node.js)” 。Select the debug configuration <your module name> Local Debug (Node.js) from the dropdown.

    • JavaJava

      • 打开 App.java 文件并添加断点。Open the file App.java and add a breakpoint.

      • 通过选择“视图”>“调试”以导航到 Visual Studio Code 调试视图 。Navigate to the Visual Studio Code Debug view by selecting View > Debug. 从下拉列表中选择调试配置“<你的模块名称> 本地调试(Java)” 。Select the debug configuration <your module name> Local Debug (Java) from the dropdown.

  2. 单击“开始调试”或按“F5”开始调试会话 。Click Start Debugging or press F5 to start the debug session.

  3. 在 Visual Studio Code 集成终端中,运行以下命令向模块发送“Hello World”消息 。In the Visual Studio Code integrated terminal, run the following command to send a Hello World message to your module. 这是在前面的步骤中设置 IoT Edge 模拟器时所显示的命令。This is the command shown in previous steps when you set up IoT Edge simulator.

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

    备注

    如果使用的是 Windows,请确保 Visual Studio Code 集成终端的 shell 为 Git Bash 或 WSL Bash 。If you are using Windows, making sure the shell of your Visual Studio Code integrated terminal is Git Bash or WSL Bash. 无法从 PowerShell 或命令提示符运行 curl 命令。You cannot run the curl command from a PowerShell or command prompt.

    提示

    还可以使用 PostMan 或其他 API 工具(而不是 curl)来发送消息。You can also use PostMan or other API tools to send messages through instead of curl.

  4. 在 Visual Studio Code 调试视图中,将在左侧面板中看到变量。In the Visual Studio Code Debug view, you'll see the variables in the left panel.

  5. 若要停止调试会话,请选择“停止”按钮或按“Shift + F5”,然后在命令面板中运行“Azure IoT Edge: 停止 IoT Edge 模拟器”以停止模拟器并清除。To stop your debugging session, select the Stop button or press Shift + F5, and then run Azure IoT Edge: Stop IoT Edge Simulator in the command palette to stop the simulator and clean up.

使用 IoT Edge 模拟器在附加模式下进行调试 (C#、Node.js、Java、Azure Functions)Debug in attach mode with IoT Edge Simulator (C#, Node.js, Java, Azure Functions)

默认解决方案包含两个模块,一个是模拟的温度传感器模块,另一个是管道模块。Your default solution contains two modules, one is a simulated temperature sensor module and the other is the pipe module. 模拟的温度传感器向管道模块发送消息,然后将消息通过管道传送到 IoT 中心。The simulated temperature sensor sends messages to the pipe module and then the messages are piped to the IoT Hub. 在创建的模块文件夹中,有适用于不同容器类型的多个 Docker 文件。In the module folder you created, there are several Docker files for different container types. 使用以扩展名“.debug”结尾的任何文件来生成用于测试的模块 。Use any of the files that end with the extension .debug to build your module for testing.

目前,仅支持以附加模式进行调试,如下所示:Currently, debugging in attach mode is supported only as follows:

  • C# 模块(包括 Azure Functions 的模块)支持在 Linux amd64 容器进行调试C# modules, including those for Azure Functions, support debugging in Linux amd64 containers
  • Node.js 模块支持在 Linux amd64、arm32v7 容器以及 Windows amd64 容器中进行调试Node.js modules support debugging in Linux amd64 and arm32v7 containers, and Windows amd64 containers
  • Java 模块支持在 Linux amd64 和 arm32v7 容器中进行调试Java modules support debugging in Linux amd64 and arm32v7 containers

提示

可以通过单击 Visual Studio 代码状态栏中的项目来切换 IoT Edge 解决方案的默认平台的选项。You can switch among options for the default platform for your IoT Edge solution by clicking the item in the Visual Studio Code status bar.

为 IoT Edge 解决方案设置 IoT Edge 模拟器Set up IoT Edge simulator for IoT Edge solution

在开发计算机中,可以启动 IoT Edge 模拟器(而不是安装 IoT Edge 安全守护程序)以运行 IoT Edge 解决方案。In your development machine, you can start an IoT Edge simulator instead of installing the IoT Edge security daemon so that you can run your IoT Edge solution.

  1. 在左侧的设备资源管理器中,右键单击 IoT Edge 设备 ID,然后选择“设置 IoT Edge 模拟器”以使用设备连接字符串启动模拟器 。In device explorer on the left side, right-click on your IoT Edge device ID, and then select Setup IoT Edge Simulator to start the simulator with the device connection string.

  2. 通过读取集成终端中的进度详细信息,可以看到 IoT Edge 模拟器已成功设置。You can see the IoT Edge Simulator has been successfully set up by reading the progress detail in the integrated terminal.

生成和运行用于调试的容器并在附加模式下进行调试Build and run container for debugging and debug in attach mode

  1. 打开模块文件 (Program.csapp.js``App.java<your module name>.cs) 并添加断点。Open your module file (Program.cs, app.js, App.java, or <your module name>.cs) and add a breakpoint.

  2. 在 Visual Studio Code 资源管理器视图中,右键单击解决方案的 deployment.debug.template.json 文件,然后选择“在模拟器中构建并运行 IoT Edge 解决方案” 。In the Visual Studio Code Explorer view, right-click the deployment.debug.template.json file for your solution and then select Build and Run IoT Edge solution in Simulator. 可以在同一窗口中监视所有模块容器日志。You can watch all the module container logs in the same window. 还可以导航到 Docker 视图以监视容器状态。You can also navigate to the Docker view to watch container status.

    监视变量

  3. 导航至 Visual Studio Code 调试视图,并选择模块的调试配置文件。Navigate to the Visual Studio Code Debug view and select the debug configuration file for your module. 调试选项名称应类似于“<你的模块名称> 远程调试” The debug option name should be similar to <your module name> Remote Debug

  4. 选择“开始调试”或按“F5” 。Select Start Debugging or press F5. 选择要附加到的进程。Select the process to attach to.

  5. 在 Visual Studio Code 调试视图中,将在左侧面板中看到变量。In Visual Studio Code Debug view, you'll see the variables in the left panel.

  6. 若要停止调试会话,请先选择停止按钮或按“Shift + F5”,然后从命令面板中选择“Azure IoT Edge: 停止 IoT Edge 模拟器”。To stop the debugging session, first select the Stop button or press Shift + F5, and then select Azure IoT Edge: Stop IoT Edge Simulator from the command palette.

备注

上面的示例展示了如何调试容器上的 IoT Edge 模块。The preceding example shows how to debug IoT Edge modules on containers. 它为模块的容器 createOptions 设置添加了公开的端口。It added exposed ports to your module's container createOptions settings. 完成模块的调试后,建议为可用于生产的 IoT Edge 模块删除那些公开的端口。After you finish debugging your modules, we recommend you remove these exposed ports for production-ready IoT Edge modules.

对于使用 C# 编写的模块(包括 Azure Functions),此示例基于 Dockerfile.amd64.debug 的调试版本,在生成容器映像时这将在容器映像中包括 .NET Core 命令行调试器 (VSDBG)。For modules written in C#, including Azure Functions, this example is based on the debug version of Dockerfile.amd64.debug, which includes the .NET Core command-line debugger (VSDBG) in your container image while building it. 对于生产就绪的 IoT Edge 模块,建议在调试完 C# 模块后在不使用 VSDBG 的情况下直接使用 Dockerfile。After you debug your C# modules, we recommend that you directly use the Dockerfile without VSDBG for production-ready IoT Edge modules.

使用 IoT Edge 运行时调试模块Debug a module with the IoT Edge runtime

每个模块文件夹中都有多个适用于不同容器类型的 Docker 文件。In each module folder, there are several Docker files for different container types. 使用以扩展名“.debug”结尾的任何文件来生成用于测试的模块 。Use any of the files that end with the extension .debug to build your module for testing.

使用此方法调试模块时,模块将在 IoT Edge 运行时的顶层运行。When debugging modules using this method, your modules are running on top of the IoT Edge runtime. IoT Edge 设备和 Visual Studio Code 可位于同一台计算机上;更常见的情况是,Visual Studio Code 位于开发计算机上,IoT Edge 运行时和模块在另一台物理计算机上运行。The IoT Edge device and your Visual Studio Code can be on the same machine, or more typically, Visual Studio Code is on the development machine and the IoT Edge runtime and modules are running on another physical machine. 若要从 Visual Studio Code 进行调试,必须:In order to debug from Visual Studio Code, you must:

  • 设置 IoT Edge 设备,使用 .debug Dockerfile 生成 IoT Edge 模块,然后将其部署到 IoT Edge 设备。Set up your IoT Edge device, build your IoT Edge module(s) with the .debug Dockerfile, and then deploy to the IoT Edge device.
  • 公开模块的 IP 和端口,以便可以附加调试程序。Expose the IP and port of the module so that the debugger can be attached.
  • 更新 launch.json,使 Visual Studio Code 能够附加到远程计算机上的容器中的进程。Update the launch.json so that Visual Studio Code can attach to the process in the container on the remote machine. 此文件位于工作区中的 .vscode 文件夹内,每当添加用于支持调试的新模块时,此文件都会更新。This file is located in the .vscode folder in your workspace and updates each time you add a new module that supports debugging.

生成模块并将其部署到 IoT Edge 设备Build and deploy your module to the IoT Edge device

  1. 在 Visual Studio 代码中,打开 deployment.debug.template.json 文件,其中包含模块映像的调试版本,并设置了正确的 createOptions 值。In Visual Studio Code, open the deployment.debug.template.json file, which contains the debug version of your module images with the proper createOptions values set.

  2. 如果正在使用 Python 开发模块,请在继续之前按照以下步骤操作:If you're developing your module in Python, follow these steps before proceeding:

    • 打开文件 main.py 并在导入部分后添加此代码:Open the file main.py and add this code after the import section:

      import ptvsd
      ptvsd.enable_attach(('0.0.0.0',  5678))
      
    • 将以下单行代码添加到要调试的回叫中:Add the following single line of code to the callback you want to debug:

      ptvsd.break_into_debugger()
      

      例如,如果要调试 receive_message_listener 函数,则应插入该行代码,如下所示:For example, if you want to debug the receive_message_listener function, you would insert that line of code as shown below:

      def receive_message_listener(client):
           ptvsd.break_into_debugger()
           global RECEIVED_MESSAGES
           while True:
               message = client.receive_message_on_input("input1")   # blocking call
               RECEIVED_MESSAGES += 1
               print("Message received on input1")
               print( "    Data: <<{}>>".format(message.data) )
               print( "    Properties: {}".format(message.custom_properties))
               print( "    Total calls received: {}".format(RECEIVED_MESSAGES))
               print("Forwarding message to output1")
               client.send_message_to_output(message, "output1")
               print("Message successfully forwarded")
      
  3. 在 Visual Studio Code 命令面板中:In the Visual Studio Code command palette:

    1. 运行“Azure IoT Edge: Build and Push IoT Edge solution”命令。Run the command Azure IoT Edge: Build and Push IoT Edge solution.

    2. 选择解决方案的 deployment.debug.template.json 文件。Select the deployment.debug.template.json file for your solution.

  4. 在 Visual Studio Code 资源管理器视图的“Azure IoT 中心设备”部分中 :In the Azure IoT Hub Devices section of the Visual Studio Code Explorer view:

    1. 右键单击 IoT Edge 设备 ID,然后选择“为单个设备创建部署”。 Right-click an IoT Edge device ID and then select Create Deployment for Single Device.

      提示

      若要确认已选择的设备为 IoT Edge 设备,请选择它以展开模块列表并验证是否存在“$ edgeHub”和“$ edgeAgent” 。To confirm that the device you've chosen is an IoT Edge device, select it to expand the list of modules and verify the presence of $edgeHub and $edgeAgent. 每个 IoT Edge 设备都包含这两个模块。Every IoT Edge device includes these two modules.

    2. 导航到解决方案的“config”文件夹,选择 deployment.debug.amd64.json 文件,然后选择“选择 Edge 部署清单” 。Navigate to your solution's config folder, select the deployment.debug.amd64.json file, and then select Select Edge Deployment Manifest.

将在集成终端中看到已成功创建部署且具有一个部署 ID。You'll see the deployment successfully created with a deployment ID in the integrated terminal.

可以通过在终端中运行 docker ps 命令来检查容器状态。You can check your container status by running the docker ps command in the terminal. 如果 Visual Studio Code 和 IoT Edge 运行时在同一台计算机上运行,则还可以在 Visual Studio Code Docker 视图中检查状态。If your Visual Studio Code and IoT Edge runtime are running on the same machine, you can also check the status in the Visual Studio Code Docker view.

为调试程序公开模块的 IP 和端口Expose the IP and port of the module for the debugger

如果模块与 Visual Studio Code 在同一台计算机上运行,你使用 localhost 附加到容器,并且 .debug Dockerfile、模块的容器 createOptions 设置和 launch.json 文件中已有正确的端口设置,则可以跳过本部分。You can skip this section if your modules are running on the same machine as Visual Studio Code, as you are using localhost to attach to the container and already have the correct port settings in the .debug Dockerfile, module's container createOptions settings, and launch.json file. 如果模块和 Visual Studio Code 在不同的计算机上运行,请根据开发语言执行以下步骤。If your modules and Visual Studio Code are running on separate machines, follow the steps for your development language.

  • C#,包括 Azure FunctionsC#, including Azure Functions

    在开发计算机和 IoT Edge 设备上配置 SSH 通道,然后编辑要附加的 launch.json 文件。Configure the SSH channel on your development machine and IoT Edge device and then edit launch.json file to attach.

  • Node.jsNode.js

    • 确保计算机上要调试的模块正在运行且可供调试程序附加,并且可从外部访问端口 9229。Make sure the module on the machine to be debugged is running and ready for debuggers to attach, and that port 9229 is accessible externally. 可以通过在调试程序计算机上打开 http://<target-machine-IP>:9229/json 对此进行验证。You can verify this by opening http://<target-machine-IP>:9229/json on the debugger machine. 此 URL 应显示有关要调试的 Node.js 模块的信息。This URL should show information about the Node.js module to be debugged.

    • 在开发计算机上打开 Visual Studio Code,然后编辑 launch.json 文件,以便 <模块名称> Remote Debug (Node.js) 配置文件(如果模块作为 Windows 容器运行,则为 <模块名称> Remote Debug (Node.js in Windows Container) 配置文件)的地址值是所要调试的计算机的 IP。On your development machine, open Visual Studio Code and then edit launch.json so that the address value of the <your module name> Remote Debug (Node.js) profile (or <your module name> Remote Debug (Node.js in Windows Container) profile if the module is running as a Windows container) is the IP of the machine being debugged.

  • JavaJava

    • 运行 ssh -f <username>@<target-machine> -L 5005:127.0.0.1:5005 -N,与要调试的计算机建立 SSH 隧道。Build an SSH tunnel to the machine to be debugged by running ssh -f <username>@<target-machine> -L 5005:127.0.0.1:5005 -N.

    • 在开发计算机上打开 Visual Studio Code,然后编辑 launch.json 中的 <模块名称> Remote Debug (Java) 配置文件,以便可以附加到目标计算机。On your development machine, open Visual Studio Code and edit the <your module name> Remote Debug (Java) profile in launch.json so that you can attach to the target machine. 若要详细了解如何编辑 launch.json 以及使用 Visual Studio Code 调试 Java,请参阅有关配置调试程序的部分。To learn more about editing launch.json and debugging Java with Visual Studio Code, see the section on configuring the debugger.

  • PythonPython

    • 确保要调试的计算机上的端口 5678 已打开且可访问。Make sure that port 5678 on the machine to be debugged is open and accessible.

    • 在前面已插入到 main.py 的代码 ptvsd.enable_attach(('0.0.0.0', 5678)) 中,将 0.0.0.0 更改为要调试的计算机的 IP 地址。In the code ptvsd.enable_attach(('0.0.0.0', 5678)) that you earlier inserted into main.py, change 0.0.0.0 to the IP address of the machine to be debugged. 再次生成、推送并部署 IoT Edge 模块。Build, push, and deploy your IoT Edge module again.

    • 在开发计算机上打开 Visual Studio Code,然后编辑 launch.json,使 <模块名称> Remote Debug (Python) 配置文件的 host 值使用目标计算机的 IP 地址而不是 localhostOn your development machine, open Visual Studio Code and then edit launch.json so that the host value of the <your module name> Remote Debug (Python) profile uses the IP address of the target machine instead of localhost.

调试模块Debug your module

  1. 在 Visual Studio Code 调试视图中,选择模块的调试配置文件。In the Visual Studio Code Debug view, select the debug configuration file for your module. 调试选项名称应类似于“<你的模块名称> 远程调试” The debug option name should be similar to <your module name> Remote Debug

  2. 打开开发语言的模块文件并添加断点:Open the module file for your development language and add a breakpoint:

    • Azure 函数 (C#) :将断点添加到文件 <your module name>.csAzure Function (C#): Add your breakpoint to the file <your module name>.cs.
    • C# :将断点添加到文件 Program.csC#: Add your breakpoint to the file Program.cs.
    • Node.js:将断点添加到文件 app.jsNode.js: Add your breakpoint to the file app.js.
    • Java:将断点添加到文件 App.javaJava: Add your breakpoint to the file App.java.
    • Python:在添加了 ptvsd.break_into_debugger() 行的回调方法中,将断点添加到文件 main.pyPython: Add your breakpoint to the file main.pyin the callback method where you added the ptvsd.break_into_debugger() line.
    • C:将断点添加到文件 main.cC: Add your breakpoint to the file main.c.
  3. 选择“开始调试”或选择 F5 。Select Start Debugging or select F5. 选择要附加到的进程。Select the process to attach to.

  4. 在 Visual Studio Code 调试视图中,将在左侧面板中看到变量。In the Visual Studio Code Debug view, you'll see the variables in the left panel.

备注

上面的示例展示了如何调试容器上的 IoT Edge 模块。The preceding example shows how to debug IoT Edge modules on containers. 它为模块的容器 createOptions 设置添加了公开的端口。It added exposed ports to your module's container createOptions settings. 完成模块的调试后,建议为可用于生产的 IoT Edge 模块删除那些公开的端口。After you finish debugging your modules, we recommend you remove these exposed ports for production-ready IoT Edge modules.

远程生成和调试模块Build and debug a module remotely

凭借近期为支持 SSH 连接而对 Docker 和 Moby 引擎所做的更改,以及 Azure IoT 工具(可以将环境设置注入 Visual Studio Code 命令面板和 Azure IoT Edge 终端)中的新设置,现在可以在远程设备上生成和调试模块。With recent changes in both the Docker and Moby engines to support SSH connections, and a new setting in Azure IoT Tools that enables injection of environment settings into the Visual Studio Code command palette and Azure IoT Edge terminals, you can now build and debug modules on remote devices.

请参阅此 IoT 开发人员博客文章获取详细信息和分步说明。See this IoT Developer blog entry for more information and step-by-step instructions.

后续步骤Next steps

生成模块后,了解如何从 Visual Studio Code 部署 Azure IoT Edge 模块After you've built your module, learn how to deploy Azure IoT Edge modules from Visual Studio Code.

若要开发用于 IoT Edge 设备的模块,请参阅了解并使用 Azure IoT 中心 SDKTo develop modules for your IoT Edge devices, Understand and use Azure IoT Hub SDKs.