다음을 통해 공유

Visual Studio Code를 사용하여 Azure IoT Edge 모듈 디버깅

  • 아티클

적용 대상: IoT Edge 1.5 확인 표시 IoT Edge 1.5 IoT Edge 1.4 확인 표시 IoT Edge 1.4

Important

IoT Edge 1.5 LTS 및 IoT Edge 1.4 LTS는 지원되는 릴리스입니다. IoT Edge 1.4 LTS는 2024년 11월 12일에 수명이 종료됩니다. 이전 릴리스에 있는 경우 IoT Edge 업데이트를 참조하세요.

이 문서에서는 Visual Studio Code를 사용하여 여러 언어로 IoT Edge 모듈을 디버그하는 방법을 보여 줍니다. 개발 컴퓨터에서 Visual Studio Code를 사용하여 로컬 또는 원격 모듈 컨테이너에서 모듈을 연결하고 디버그할 수 있습니다.

이 문서에는 두 개의 IoT Edge 개발 도구에 대한 단계가 포함되어 있습니다.

  • Azure IoT Edge Dev Tool CLI(명령줄 도구). 이 도구는 개발에 기본 설정됩니다.
  • Visual Studio Code용 Azure IoT Edge 도구 확장. 확장이 유지 관리 모드에 있습니다.

이 문서의 시작 부분에 있는 도구 선택기 단추를 사용하여 도구 버전을 선택합니다.

Visual Studio Code는 다음 프로그래밍 언어로 IoT Edge 모듈 작성을 지원합니다.

  • C# 및 C# Azure Functions
  • C
  • Python
  • Node.js
  • Java

Azure IoT Edge는 다음의 디바이스 아키텍처를 지원합니다.

  • AMD64
  • ARM32v7
  • ARM64

지원되는 운영 체제, 언어 및 아키텍처에 대한 자세한 내용은 언어 및 아키텍처 지원을 참조하세요.

Visual Studio Code IoT Edge 확장을 사용하는 경우 IoT Edge 시뮬레이터에서 모듈 코드를 시작하고 디버그할 수도 있습니다.

IoT EFLOW(Edge for Linux on Windows)를 사용하여 Linux 컨테이너에서 Windows 개발 컴퓨터 및 디버그 모듈을 사용할 수도 있습니다. EFLOW를 사용하여 모듈을 개발하는 방법에 대한 자세한 내용은 자습서: IoT Edge for Linux on Windows를 사용하여 Linux 컨테이너로 IoT Edge 모듈 개발을 참조하세요.

Visual Studio Code의 디버깅 기능에 익숙하지 않은 경우, Visual Studio Code 디버깅을 참조하세요.

필수 조건

Windows, macOS 또는 Linux를 실행하는 컴퓨터 또는 가상 머신을 개발 머신으로 사용할 수 있습니다. Windows 컴퓨터에서는 Windows 또는 Linux 모듈을 개발할 수 있습니다. Linux 모듈을 개발하려면 Docker Desktop에 대한 요구 사항을 충족하는 Windows 컴퓨터를 사용해야 합니다.

개발 및 디버깅에 필요한 도구를 설치하려면 Visual Studio Code를 사용하여 Azure IoT Edge 모듈 개발 자습서를 완료합니다.

Visual Studio Code를 설치합니다.

다음 확장을 추가합니다.

디바이스에서 모듈을 디버깅하려면 다음이 필요합니다.

  • 하나 이상의 IoT Edge 디바이스가 있는 활성 IoT Hub.
  • 물리적 IoT Edge 디바이스 또는 가상 디바이스. Azure에서 가상 디바이스를 만들려면 Linux용 빠른 시작의 단계를 따릅니다.
  • 사용자 지정 IoT Edge 모듈. 사용자 지정 모듈을 만들려면 Visual Studio Code를 사용하여 Azure IoT Edge 모듈 개발 자습서의 단계를 따릅니다.

IoT Edge 시뮬레이터를 사용하여 컨테이너 없이 디버그

IoT Edge 시뮬레이터는 개발 컴퓨터에서 실행되고 단일 IoT Edge 디바이스의 동작을 시뮬레이션하는 도구입니다. IoT Edge 시뮬레이터를 사용하면 물리적 디바이스나 전체 IoT Edge 디바이스 런타임 없이 IoT Edge 모듈을 개발하고 테스트할 수 있습니다.

다음 디버깅 단계에서는 사용자 지정 모듈을 이미 만들었다고 가정합니다. 사용자 지정 모듈을 만들지 않은 경우 Visual Studio Code를 사용하여 Azure IoT Edge 모듈 개발 자습서의 단계를 따릅니다.

C 또는 Python을 사용하는 경우 컨테이너 없이 모듈을 디버깅할 수 없습니다.

IoT Edge 시뮬레이터를 사용하여 연결 모드에서 디버그

연결 모드의 디버깅은 C 또는 Python에서 지원되지 않습니다.

IoT Edge 런타임을 사용하여 모듈 디버그

각 모듈 폴더에는 서로 다른 컨테이너 유형에 사용되는 여러 Docker 파일이 있습니다. .debug 확장명으로 끝나는 파일을 사용하여 테스트할 모듈을 빌드합니다.

이 방법을 사용하여 모듈을 디버그하는 경우에는 모듈이 IoT Edge 런타임을 기반으로 실행됩니다. IoT Edge 디바이스와 Visual Studio Code가 동일한 머신에 있는 경우도 있지만, Visual Studio Code는 개발 머신에 있고 IoT Edge 런타임과 모듈은 다른 물리적 머신에서 실행되는 경우가 보다 일반적입니다. Visual Studio Code에서 디버깅하려면 다음을 수행해야 합니다.

  • IoT Edge 디바이스를 설정하고 .debug Dockerfile로 IoT Edge 모듈을 빌드한 다음, IoT Edge 디바이스에 배포합니다.
  • Visual Studio Code에서 원격 머신의 컨테이너에 있는 프로세스에 연결할 수 있도록 launch.json을 업데이트합니다. 이 파일은 작업 영역의 .vscode 폴더에서 찾을 수 있으며 디버깅을 지원하는 새 모듈을 추가할 때마다 업데이트됩니다.
  • 원격 SSH 디버깅을 사용하여 원격 컴퓨터의 컨테이너에 연결합니다.

모듈을 빌드하고 IoT Edge 디바이스에 배포

Visual Studio Code에서 deployment.debug.template.json 배포 매니페스트 파일을 엽니다. 배포 매니페스트는 대상 IoT Edge 디바이스에 구성할 모듈을 설명합니다. 배포하기 전에 Azure Container Registry 자격 증명 및 모듈 이미지를 적절한 createOptions 값으로 업데이트해야 합니다. createOption 값에 대한 자세한 내용은 IoT Edge 모듈에 대한 컨테이너 만들기 옵션 구성 방법을 참조하세요.

  1. Azure Container Registry를 사용하여 모듈 이미지를 저장하는 경우 자격 증명을 deployment.template.json의 edgeAgent>settings>registryCredentials 섹션에 추가합니다. 두 위치 모두에서myacr을 사용자 고유의 레지스트리 이름으로 바꾸고 암호와 로그인 서버 주소를 입력합니다. 예시:

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

  2. 나열된 각 시스템(edgeHub 및 edgeAgent) 및 사용자 지정 모듈(예: filtermodule)에 대한 createOptions 값에 다음 문자열화된 콘텐츠를 추가하거나 바꿉니다. 필요한 경우 값을 변경합니다.

    "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

    예를 들어 filtermodule 구성은 다음과 유사해야 합니다.

    "filtermodule": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
    "image": "myacr.azurecr.io/filtermodule:0.0.1-amd64",
    "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
}
  1. Visual Studio Code 명령 팔레트에서 Azure IoT Edge: IoT Edge 솔루션 빌드 및 푸시 명령을 실행합니다.
  2. 솔루션의 deployment.debug.template.json 파일을 선택합니다.
  3. Visual Studio Code 탐색기 보기의 Azure IoT Hub>디바이스 섹션에서 마우스 오른쪽 단추로 배포할 IoT Edge 디바이스 이름을 클릭한 다음, 단일 디바이스에 대한 배포 만들기를 선택합니다.

    팁

    선택한 디바이스가 IoT Edge 디바이스인지 확인하려면 선택하여 모듈 목록을 확장하고 $edgeHub 및 $edgeAgent가 있는지 확인합니다. 모든 IoT Edge 디바이스에 이러한 두 모듈이 포함됩니다.

  4. 솔루션의 config 폴더로 이동하고, deployment.debug.amd64.json 파일을 선택한 다음, Edge 배포 매니페스트 선택을 선택합니다.

터미널에서 docker ps 명령을 실행하여 디바이스 또는 가상 머신에서 컨테이너 상태를 확인할 수 있습니다. 명령을 실행하면 컨테이너 목록이 표시됩니다. Visual Studio Code와 IoT Edge 런타임이 동일한 머신에서 실행되는 경우 Visual Studio Code Docker 보기에서 상태를 확인할 수도 있습니다.

Important

Azure Container Registry와 같은 프라이빗 레지스트리를 이미지에 사용하는 경우 이미지를 푸시하려면 인증해야 할 수 있습니다. docker login <Azure Container Registry login server> 또는 az acr login --name <Azure Container Registry name>를 사용하여 인증합니다.

Docker에 로그인

레지스트리의 스토리지에 컨테이너 이미지를 푸시할 수 있도록 Docker에 컨테이너 레지스트리 자격 증명을 제공합니다.

  1. 레지스트리를 만든 후 저장한 Azure Container Registry 자격 증명을 사용하여 Docker에 로그인합니다.

    docker login -u <Azure Container Registry username> -p <Azure Container Registry password> <Azure Container Registry login server>

    --password-stdin 사용을 권장하는 보안 경고가 표시될 수 있습니다. 이 모범 사례는 프로덕션 시나리오에 적합하지만 이 자습서의 범위에는 포함되지 않습니다. 자세한 내용은 docker login 참조를 참조하세요.

  2. Azure Container Registry에 로그인합니다. az 명령을 사용하려면 Azure CLI를 설치해야 할 수도 있습니다. 이 명령은 설정>액세스 키의 컨테이너 레지스트리에 있는 사용자 이름과 암호를 요청합니다.

    az acr login -n <Azure Container Registry name>

팁

이 자습서의 어느 시점에서든 로그아웃한 경우 계속 진행하려면 Docker 및 Azure Container Registry 로그인 단계를 반복하세요.

모듈 Docker 이미지 빌드

모듈의 Dockerfile을 사용하여 모듈 Docker 이미지를 빌드합니다.

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

예를 들어 로컬 레지스트리 또는 Azure Container Registry에 대한 이미지를 빌드하려면 다음 명령을 사용합니다.

# Build the image for the local registry

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

# Or build the image for an Azure Container Registry

docker build --rm -f "./modules/filtermodule/Dockerfile.amd64.debug" -t myacr.azurecr.io/filtermodule:0.0.1-amd64 "./modules/filtermodule"

모듈 Docker 이미지 푸시

모듈 이미지를 로컬 레지스트리 또는 컨테이너 레지스트리에 푸시합니다.

docker push <ImageName>

예시:

# Push the Docker image to the local registry

docker push localhost:5000/filtermodule:0.0.1-amd64

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

IoT Edge 디바이스에 모듈 배포

IoT Edge Azure CLI set-modules 명령을 사용하여 모듈을 Azure IoT Hub에 배포합니다. 예를 들어 deployment.debug.template.json 파일에 정의된 모듈을 my-device IoT Edge 디바이스에 대한 my-iot-hub IoT Hub에 배포하려면 다음 명령을 사용합니다.

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.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SharedAccessKey>"

팁

IoT Hub 공유 액세스 키는 Azure Portal의 IoT Hub >보안 설정>공유 액세스 정책>iothubowner에서 찾을 수 있습니다.

모듈 디버그

원격 디바이스에서 모듈을 디버그하려면 Visual Studio Code에서 원격 SSH 디버깅을 사용할 수 있습니다.

Visual Studio Code 원격 디버깅을 사용하도록 설정하려면 원격 개발 확장을 설치합니다. Visual Studio Code 원격 디버깅에 대한 자세한 내용은 Visual Studio Code 원격 개발을 참조하세요.

Visual Studio Code에서 원격 SSH 디버깅을 사용하는 방법에 대한 자세한 내용은 SSH를 사용하여 원격 개발을 참조하세요.

Visual Studio Code 디버그 보기에서 모듈의 디버그 구성 파일을 선택합니다. 기본적으로 .debug Dockerfile, 모듈의 컨테이너 createOptions 설정 및 launch.json 파일에서 localhost를 사용합니다.

디버깅 시작을 선택하거나 F5 키를 누릅니다. 연결할 프로세스를 선택합니다. Visual Studio Code 디버그 보기의 왼쪽 패널에 변수가 표시됩니다.

Docker 원격 SSH를 사용하여 디버그

Docker 및 Moby 엔진은 컨테이너에 대한 SSH 연결을 지원하여 원격 디바이스에 연결된 Visual Studio Code에서 디버그할 수 있습니다. 이 기능을 사용하려면 다음 필수 조건을 충족해야 합니다.

원격 SSH 디버깅 필수 구성 요소는 사용 중인 언어에 따라 다를 수 있습니다. 다음 섹션에서는 .NET 설정에 대해 설명합니다. 다른 언어에 대한 자세한 내용은 SSH를 사용한 원격 개발의 개요를 참조하세요. 원격 디버깅을 구성하는 방법에 대한 자세한 내용은 Visual Studio Code 설명서의 각 언어에 대한 디버깅 섹션에 포함되어 있습니다.

Docker SSH 터널링 구성

  1. Docker SSH 터널링의 단계에 따라 개발 컴퓨터에서 SSH 터널링을 구성합니다. SSH 터널링에는 퍼블릭/프라이빗 키 쌍 인증 및 원격 디바이스 엔드포인트를 정의하는 Docker 컨텍스트가 필요합니다.

  2. Docker에 연결하려면 루트 수준 권한이 필요합니다. 루트가 아닌 사용자로 docker 관리의 단계에 따라 원격 디바이스에서 Docker 디먼에 대한 연결을 허용합니다. 디버깅이 완료되면 Docker 그룹에서 사용자를 제거할 수 있습니다.

  3. Visual Studio Code에서 명령 팔레트(Ctrl+Shift+P)를 사용하여 Docker Context: Use 명령을 내려서 원격 컴퓨터를 가리키는 Docker 컨텍스트를 활성화합니다. 이 명령을 사용하면 Visual Studio Code 및 Docker CLI에서 모두 원격 컴퓨터 컨텍스트를 사용합니다.

    팁

    모든 Docker 명령은 현재 컨텍스트를 사용합니다. 디버깅이 완료되면 컨텍스트를 다시 기본값으로 변경해야 합니다.

  4. 원격 Docker 컨텍스트가 활성 상태인지 확인하려면 원격 디바이스에서 실행 중인 컨테이너를 나열합니다.

    docker ps

    출력에 다음과 비슷한 원격 디바이스에서 실행되는 컨테이너가 나열됩니다.

    PS C:\> docker ps        
CONTAINER ID   IMAGE                                                             COMMAND                   CREATED        STATUS         PORTS                                                                                                                                   NAMES
a317b8058786   myacr.azurecr.io/filtermodule:0.0.1-amd64                         "dotnet filtermodule…"    24 hours ago   Up 6 minutes                                                                                                                                           filtermodule
d4d949f8dfb9   mcr.microsoft.com/azureiotedge-hub:1.5                            "/bin/sh -c 'echo \"$…"   24 hours ago   Up 6 minutes   0.0.0.0:443->443/tcp, :::443->443/tcp, 0.0.0.0:5671->5671/tcp, :::5671->5671/tcp, 0.0.0.0:8883->8883/tcp, :::8883->8883/tcp, 1883/tcp   edgeHub
1f0da9cfe8e8   mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0   "/bin/sh -c 'echo \"$…"   24 hours ago   Up 6 minutes                                                                                                    
                                       tempSensor
66078969d843   mcr.microsoft.com/azureiotedge-agent:1.5                          "/bin/sh -c 'exec /a…"    24 hours ago   Up 6 minutes                                                                                                    
                                       edgeAgent

  5. .vscode 디렉터리에서 Visual Studio Code로 파일을 열어 launch.json에 새 구성을 추가합니다. 구성 추가를 선택한 다음, 모듈에 대해 일치하는 원격 연결 템플릿을 선택합니다. 예를 들어.NET Core에 대한 구성은 다음과 같습니다. PipeArgs의 -H 매개 변수 값을 디바이스 DNS 이름 또는 IP 주소로 변경합니다.

    "configurations": [
{
  "name": "Remote Debug IoT Edge Module (.NET Core)",
  "type": "coreclr",
  "request": "attach",
  "processId": "${command:pickRemoteProcess}",
  "pipeTransport": {
    "pipeProgram": "docker",
    "pipeArgs": [
      "-H",
      "ssh://user@my-device-vm.eastus.cloudapp.azure.com:22",
      "exec",
      "-i",
      "filtermodule",
      "sh",
      "-c"
    ],
    "debuggerPath": "~/vsdbg/vsdbg",
    "pipeCwd": "${workspaceFolder}",
    "quoteArgs": true
  },
  "sourceFileMap": {
    "/app": "${workspaceFolder}/modules/filtermodule"
  },
  "justMyCode": true
},

모듈 원격 디버그

  1. Visual Studio Code 디버그 보기에서 원격 디버그 IoT Edge 모듈(.NET Core) 디버그 구성을 선택합니다.

  2. 디버깅 시작을 선택하거나 F5 키를 누릅니다. 연결할 프로세스를 선택합니다.

  3. Visual Studio Code 디버그 보기의 왼쪽 패널에 변수가 표시됩니다.

  4. Visual Studio Code에서 중단점을 사용자 지정 모듈에 설정합니다.

  5. 중단점에 도달하면 변수를 검사하고, 코드를 단계별로 실행하고, 모듈을 디버그할 수 있습니다.

    중단점에서 일시 중지된 원격 디바이스의 Docker 컨테이너에 연결된 Visual Studio Code의 스크린샷.

참고 항목

앞의 예제에서는 원격 컨테이너에서 IoT Edge 모듈을 디버그하는 방법을 보여 줍니다. 이 예제에서는 원격 Docker 컨텍스트를 추가하고 원격 디바이스에 대한 Docker 권한을 변경합니다. 모듈 디버깅을 완료한 후 Docker 컨텍스트를 기본값으로 설정하고 사용자 계정에서 권한을 제거합니다.

Raspberry Pi 디바이스를 사용하는 예제는 이 IoT 개발자 블로그 항목을 참조하세요.

다음 단계

모듈을 빌드한 후 Azure IoT Edge 모듈을 배포하는 방법을 알아봅니다.

IoT Edge 디바이스용 모듈을 개발하려면 Azure IoT Hub SDK를 이해하고 사용합니다.