Visual Studio Code を使用して Azure IoT Edge モジュールをデバッグする

  • [アーティクル]

適用対象:IoT Edge 1.5 のチェックマーク IoT Edge 1.5 IoT Edge 1.4 チェックマーク IoT Edge 1.4

重要

サポートされているリリースは、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 を使用して、モジュールをローカルまたはリモートのモジュール コンテナーにアタッチしてデバッグできます。

この記事には、2 つの IoT Edge 開発ツールの手順が含まれています。

  • "Azure IoT Edge 開発ツール" コマンド ライン ツール (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

サポートされているオペレーティング システム、言語、およびアーキテクチャの詳細については、「Language and architecture support (言語とアーキテクチャのサポート)」を参照してください。

Visual Studio Code IoT Edge 拡張機能を使用する場合は、IoT Edge シミュレーターでモジュール コードを起動してデバッグすることもできます。

IoT Edge for Linux on Windows (EFLOW) を使用して、Windows 開発用コンピューターを使用し、Linux コンテナー内のモジュールをデバッグすることもできます。 モジュールの開発に 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 をインストールします

次の拡張機能を追加します。

デバイス上でモジュールをデバッグするには、以下が必要です。

  • 少なくとも 1 つの IoT Edge デバイスを含むアクティブな IoT Hub。
  • 物理 IoT Edge デバイスまたは仮想デバイス。 Azure で仮想デバイスを作成するには、Linux 用のクイック スタートの手順に従ってください。
  • カスタム IoT Edge モジュール。 カスタム モジュールを作成するには、チュートリアル「Visual Studio Code を使用して Azure IoT Edge モジュールを開発する」の手順に従ってください。

IoT Edge シミュレーターを使用してコンテナーなしでデバッグする

IoT Edge シミュレーターは、開発用コンピューター上で実行され、1 つの 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 デバイスにデプロイします。
  • launch.json を更新し、Visual Studio Code が、リモート マシン上のコンテナー内にあるプロセスにアタッチできるようにします。 このファイルは、ワークスペース内の .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.debug.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: Build and Push IoT Edge solution](Azure IoT Edge: IoT Edge ソリューションのビルドとプッシュ) コマンドを実行します。
  2. 対象のソリューションの deployment.debug.template.json ファイルを選択します。
  3. Visual Studio Code エクスプローラー ビューの [Azure IoT Hub]>[デバイス] セクションで、デプロイの IoT Edge デバイス名を右クリックし、[Create Deployment for Single Device] (単一デバイスのデプロイの作成) を選択します。

    ヒント

    選択したデバイスが IoT Edge デバイスであることを確認するには、そのデバイスを選択してモジュールの一覧を展開し、[$edgeHub] と [$edgeAgent] が存在することを確認します。 すべての IoT Edge デバイスには、これらの 2 つのモジュールが含まれています。

  4. ソリューションの config フォルダーに移動し、deployment.debug.amd64.json ファイルを選択して、[Select Edge Deployment Manifest]\(Edge 配置マニフェストの選択\) を選択します。

ターミナルで docker ps コマンドを実行して、デバイスまたは仮想マシンからコンテナーの状態を確認できます。 このコマンドを実行すると、コンテナーが一覧表示されます。 Visual Studio Code と IoT Edge ランタイムが同じマシン上で実行されている場合は、Visual Studio Code の Docker ビューでも状態を確認することができます。

重要

イメージに 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 ファイルに定義されているモジュールを IoT Edge デバイス my-deviceの IoT Hub my-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 共有アクセス キーは、IoT Hub >セキュリティ設定>の [共有アクセス ポリシー]>iothubowner の Azure portal にあります。

モジュールをデバッグする

リモート デバイスでモジュールをデバッグするには、Visual Studio Code でリモート SSH デバッグを使用します。

Visual Studio Code のリモート デバッグを有効にするには、Remote Development 拡張機能をインストールします。 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 に接続するには、root レベルの特権が必要です。 非 root ユーザーとしての Docker の管理に関するページの手順に従って、リモート デバイスでの Docker デーモンへの接続を許可します。 デバッグが完了したら、Docker グループからユーザーを削除できます。

  3. Visual Studio Code で、コマンド パレット (Ctrl + Shift + P) を使用して "[Docker コンテキスト: 使用]" コマンドを発行し、リモート マシンを指す 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 デバッグ ビューで、デバッグ構成 [Remote Debug IoT Edge Module (.NET Core)] (リモート デバッグ IoT Edge モジュール (.NET Core)) を選択します。

  2. [デバッグの開始] を選択するか、F5 を押します。 アタッチするプロセスを選択します。

  3. Visual Studio Code の [デバッグ] ビューの左側のパネルに変数が表示されます。

  4. Visual Studio Code で、カスタム モジュールにブレークポイントを設定します。

  5. ブレークポイントにヒットすると、変数の検査、コードのステップ実行、モジュールのデバッグを行うことができます。

    ブレークポイントで一時停止したリモート デバイス上の Docker コンテナーにアタッチされた Visual Studio Code のスクリーンショット。

Note

前の例は、リモート コンテナー上の IoT Edge モジュールをデバッグする方法を示しています。 この例では、リモート Docker コンテキストを追加し、リモート デバイスでの Docker 特権に対する変更を加えています。 モジュールのデバッグが完了したら、Docker コンテキストを "既定値" に設定し、ユーザー アカウントから特権を削除してください。

Raspberry Pi デバイスの使用例については、この IoT Developer ブログ エントリを参照してください。

次のステップ

モジュールをビルドしたら、Visual Studio Code から Azure IoT Edge モジュールをデプロイする方法を確認してください。

お使いの IoT Edge デバイス用のモジュールを開発する方法について詳しくは、Azure IoT Hub SDK に関するページをご覧ください。