Men-debug modul Azure IoT Edge menggunakan Visual Studio Code

  • Artikel

Berlaku untuk:Tanda centang IoT Edge 1.5 IoT Edge 1.5 Tanda centang IoT Edge 1.4 IoT Edge 1.4

Penting

IoT Edge 1.5 LTS dan IoT Edge 1.4 LTS adalah rilis yang didukung. IoT Edge 1.4 LTS adalah akhir masa pakai pada 12 November 2024. Jika Anda menggunakan rilis sebelumnya, lihat Memperbarui IoT Edge.

Artikel ini memperlihatkan kepada Anda cara menggunakan Visual Studio Code untuk men-debug modul IoT Edge dalam beberapa bahasa. Di komputer pengembangan, Anda dapat menggunakan Visual Studio Code untuk melampirkan dan men-debug modul Anda dalam kontainer modul lokal atau jarak jauh.

Artikel ini mencakup langkah-langkah untuk dua alat pengembangan IoT Edge.

  • Alat baris perintah (CLI) Azure IoT Edge Dev Tool . Alat ini lebih disukai untuk pengembangan.
  • Alat Azure IoT Edge untuk ekstensi Visual Studio Code . Ekstensi dalam mode pemeliharaan.

Gunakan tombol pemilih alat di awal artikel ini untuk memilih versi alat.

Visual Studio Code mendukung penulisan modul IoT Edge dalam bahasa pemrograman berikut:

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

Azure IoT Edge mendukung arsitektur perangkat berikut:

  • AMD64
  • ARM32v7
  • ARM64

Untuk informasi selengkapnya tentang sistem operasi, bahasa, dan arsitektur yang didukung, lihat Dukungan bahasa dan arsitektur.

Saat menggunakan ekstensi IoT Edge Visual Studio Code, Anda juga dapat meluncurkan dan men-debug kode modul Anda di Simulator IoT Edge.

Anda juga dapat menggunakan komputer pengembangan Windows dan modul debug dalam kontainer Linux menggunakan IoT Edge untuk Linux di Windows (EFLOW). Untuk informasi selengkapnya tentang menggunakan EFLOW untuk mengembangkan modul, lihat Tutorial: Mengembangkan modul IoT Edge dengan kontainer Linux menggunakan IoT Edge untuk Linux di Windows.

Jika Anda tidak terbiasa dengan kemampuan penelusuran kesalahan Visual Studio Code, lihat Penelusuran kesalahan Visual Studio Code.

Prasyarat

Anda dapat menggunakan komputer atau komputer virtual yang menjalankan Windows, macOS, atau Linux sebagai komputer pengembangan Anda. Di komputer Windows, Anda dapat mengembangkan modul Windows atau Linux. Untuk mengembangkan modul Linux, gunakan komputer Windows yang memenuhi persyaratan untuk Docker Desktop.

Untuk menginstal alat yang diperlukan untuk pengembangan dan penelusuran kesalahan, selesaikan tutorial Mengembangkan modul Azure IoT Edge menggunakan Visual Studio Code .

Pasang Visual Studio Code.

Tambahkan ekstensi berikut:

Untuk men-debug modul di perangkat, Anda memerlukan:

Debug tanpa kontainer menggunakan simulator IoT Edge

Simulator IoT Edge adalah alat yang berjalan di komputer pengembangan Anda dan mensimulasikan perilaku satu perangkat IoT Edge. Anda dapat menggunakan Simulator IoT Edge untuk mengembangkan dan menguji modul IoT Edge Anda tanpa perangkat fisik atau runtime perangkat IoT Edge penuh.

Langkah-langkah penelusuran kesalahan berikut mengasumsikan Anda telah membuat modul kustom. Jika Anda belum membuat modul kustom, ikuti langkah-langkah dalam tutorial Mengembangkan Azure IoT Edge menggunakan Visual Studio Code .

Men-debug modul tanpa kontainer tidak tersedia saat menggunakan C atau Python.

Debug dalam mode lampirkan menggunakan simulator IoT Edge

Penelusuran kesalahan dalam mode lampirkan tidak didukung untuk C atau Python.

Menelusuri kesalahan modul dengan runtime IoT Edge

Di setiap folder modul, ada beberapa file Docker untuk jenis kontainer yang berbeda. Gunakan salah satu file yang diakhiri dengan ekstensi .debug guna membangun modul Anda untuk pengujian.

Saat Anda men-debug modul menggunakan metode ini, modul Anda berjalan di atas runtime IoT Edge. Perangkat IoT Edge dan Visual Studio Code Anda dapat berada di komputer yang sama, atau lebih umum lagi, Visual Studio Code ada di komputer pengembangan serta runtime dan modul IoT Edge berjalan di komputer fisik lain. Untuk men-debug dari Visual Studio Code, Anda harus:

  • Siapkan perangkat IoT Edge Anda, buat modul IoT Edge Anda dengan Dockerfile .debug , lalu sebarkan ke perangkat IoT Edge.
  • Perbarui launch.json sehingga Visual Studio Code dapat melampirkan ke proses dalam kontainer pada komputer jarak jauh. Anda dapat menemukan file ini di .vscode folder di ruang kerja Anda, dan diperbarui setiap kali Anda menambahkan modul baru yang mendukung penelusuran kesalahan.
  • Gunakan penelusuran kesalahan SSH Jarak Jauh untuk melampirkan ke kontainer pada komputer jarak jauh.

Membangun dan menyebarkan modul Anda ke perangkat IoT Edge

Di Visual Studio Code, buka file manifes penyebaran deployment.debug.template.json . Manifes penyebaran menjelaskan modul yang akan dikonfigurasi pada perangkat IoT Edge yang ditargetkan. Sebelum penyebaran, Anda perlu memperbarui kredensial Azure Container Registry dan gambar modul Anda dengan nilai yang tepat createOptions . Untuk informasi selengkapnya tentang nilai createOption, lihat Cara mengonfigurasi opsi pembuatan kontainer untuk modul IoT Edge.

  1. Jika Anda menggunakan Azure Container Registry untuk menyimpan gambar modul Anda, tambahkan kredensial Anda ke bagian registri pengaturan>edgeAgentCredentials> di deployment.debug.template.json. Ganti myacr dengan nama registri Anda sendiri di kedua tempat dan berikan kata sandi dan Alamat server masuk Anda. Contohnya:

    "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. Tambahkan atau ganti konten string berikut ke nilai createOptions untuk setiap sistem (edgeHub dan edgeAgent) dan modul kustom (misalnya, filtermodule) tercantum. Ubah nilai jika perlu.

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

    Misalnya, konfigurasi filtermodule harus mirip dengan:

    "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. Di palet perintah Visual Studio Code, jalankan perintah Azure IoT Edge: Bangun dan Dorong solusi IoT Edge.
  2. Pilih file deployment.debug.template.json untuk solusi Anda.
  3. Di bagian Perangkat Azure IoT Hub>dari tampilan Visual Studio Code Explorer, klik kanan nama perangkat IoT Edge untuk penyebaran lalu pilih Buat Penyebaran untuk Perangkat Tunggal.

    Tip

    Untuk mengonfirmasi bahwa perangkat yang Anda pilih adalah perangkat IoT Edge, pilih perangkat tersebut untuk meluaskan daftar modul dan memverifikasi keberadaan $edgeHub dan $edgeAgent. Setiap perangkat IoT Edge menyertakan dua modul ini.

  4. Buka folder config solusi Anda, pilih file deployment.debug.amd64.json, lalu pilih Pilih Manifes Penyebaran Azure Stack Edge.

Anda dapat memeriksa status kontainer dari perangkat atau komputer virtual dengan menjalankan docker ps perintah di terminal. Anda akan melihat kontainer Anda tercantum setelah menjalankan perintah. Jika Visual Studio Code dan runtime IoT Edge Anda berjalan pada komputer yang sama, Anda juga dapat memeriksa status dalam tampilan Docker Visual Studio Code.

Penting

Jika Anda menggunakan registri privat seperti Azure Container Registry untuk gambar Anda, Anda mungkin perlu mengautentikasi untuk mendorong gambar. Gunakan docker login <Azure Container Registry login server> atau az acr login --name <Azure Container Registry name> untuk mengautentikasi.

Masuk ke Docker

Berikan kredensial registri kontainer Anda ke Docker sehingga dapat mendorong gambar kontainer Anda ke penyimpanan di registri.

  1. Masuk ke Docker dengan kredensial Azure Container Registry yang Anda simpan setelah membuat registri.

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

    Anda mungkin menerima peringatan keamanan yang menyarankan penggunaan --password-stdin. Meskipun itu adalah praktik terbaik yang direkomendasikan untuk skenario produksi, itu di luar cakupan tutorial ini. Untuk mengetahui informasi selengkapnya, lihat referensi masuk docker.

  2. Masuk ke Azure Container Registry. Anda mungkin perlu Menginstal Azure CLI untuk menggunakan az perintah . Perintah ini meminta nama pengguna dan kata sandi Anda yang ditemukan di registri kontainer Anda di kunci Pengaturan> Access.

    az acr login -n <Azure Container Registry name>

Tip

Jika Anda keluar kapan saja dalam tutorial ini, ulangi langkah-langkah masuk Docker dan Azure Container Registry untuk melanjutkan.

Gambar Docker modul build

Gunakan Dockerfile modul untuk membangun gambar Docker modul.

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

Misalnya, untuk membangun gambar untuk registri lokal atau Azure Container Registry, gunakan perintah berikut:

# 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"

Mendorong gambar Docker modul

Dorong gambar modul Anda ke registri lokal atau registri kontainer.

docker push <ImageName>

Contohnya:

# 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

Menyebarkan modul ke perangkat IoT Edge

Gunakan perintah set-modul IoT Edge Azure CLI untuk menyebarkan modul ke Azure IoT Hub. Misalnya, untuk menyebarkan modul yang ditentukan dalam file deployment.debug.template.json ke IoT Hub my-iot-hub untuk perangkat IoT Edge perangkat saya, gunakan perintah berikut:

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>"

Tip

Anda dapat menemukan kunci akses bersama IoT Hub di portal Azure di pengaturan>Keamanan IoT Hub> Anda Kebijakan>akses bersama iothubowner.

Menelusuri kesalahan modul Anda

Untuk men-debug modul pada perangkat jarak jauh, Anda dapat menggunakan penelusuran kesalahan SSH Jarak Jauh di Visual Studio Code.

Untuk mengaktifkan penelusuran kesalahan jarak jauh Visual Studio Code, instal ekstensi Pengembangan Jarak Jauh. Untuk informasi selengkapnya tentang penelusuran kesalahan jarak jauh Visual Studio Code, lihat Pengembangan Jarak Jauh Visual Studio Code.

Untuk detail tentang cara menggunakan penelusuran kesalahan SSH Jarak Jauh di Visual Studio Code, lihat Pengembangan Jarak Jauh menggunakan SSH

Dalam tampilan Debug Visual Studio Code, pilih file konfigurasi debug untuk modul Anda. Secara default, .debug Dockerfile, pengaturan kontainer createOptions modul, dan launch.json file menggunakan localhost.

Pilih Mulai Debug atau pilih F5. Pilih proses yang akan dilampirkan. Dalam tampilan Debug Visual Studio Code, Anda akan melihat variabel di panel kiri.

Debug menggunakan Docker Remote SSH

Mesin Docker dan Moby mendukung koneksi SSH ke kontainer yang memungkinkan Anda melakukan debug di Visual Studio Code yang terhubung ke perangkat jarak jauh. Anda perlu memenuhi prasyarat berikut sebelum dapat menggunakan fitur ini.

Prasyarat penelusuran kesalahan SSH jarak jauh mungkin berbeda tergantung pada bahasa yang Anda gunakan. Bagian berikut menjelaskan penyiapan untuk .NET. Untuk informasi tentang bahasa lain, lihat Pengembangan Jarak Jauh menggunakan SSH untuk gambaran umum. Detail tentang cara mengonfigurasi penelusuran kesalahan jarak jauh disertakan di bagian penelusuran kesalahan untuk setiap bahasa dalam dokumentasi Visual Studio Code.

Mengonfigurasi penerowongan Docker SSH

  1. Ikuti langkah-langkah dalam penerowongan Docker SSH untuk mengonfigurasi penerowongan SSH di komputer pengembangan Anda. Penerowongan SSH memerlukan autentikasi pasangan kunci publik/privat dan konteks Docker yang menentukan titik akhir perangkat jarak jauh.

  2. Koneksi ke Docker memerlukan hak istimewa tingkat akar. Ikuti langkah-langkah dalam Mengelola docker sebagai pengguna non-root untuk mengizinkan koneksi ke daemon Docker di perangkat jarak jauh. Setelah menyelesaikan penelusuran kesalahan, Anda mungkin ingin menghapus pengguna dari grup Docker.

  3. Di Visual Studio Code, gunakan Palet Perintah (Ctrl+Shift+P) untuk mengeluarkan perintah Konteks Docker: Gunakan untuk mengaktifkan konteks Docker yang menunjuk ke komputer jarak jauh. Perintah ini menyebabkan Visual Studio Code dan Docker CLI menggunakan konteks komputer jarak jauh.

    Tip

    Semua perintah Docker menggunakan konteks saat ini. Ingatlah untuk mengubah konteks kembali ke default saat Anda selesai melakukan penelusuran kesalahan.

  4. Untuk memverifikasi konteks Docker jarak jauh aktif, cantumkan kontainer yang sedang berjalan di perangkat jarak jauh:

    docker ps

    Output harus mencantumkan kontainer yang berjalan pada perangkat jarak jauh yang serupa:

    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. Di direktori .vscode, tambahkan konfigurasi baru ke launch.json dengan membuka file di Visual Studio Code. Pilih Tambahkan konfigurasi lalu pilih templat lampiran jarak jauh yang cocok untuk modul Anda. Misalnya, konfigurasi berikut adalah untuk .NET Core. Ubah nilai untuk parameter -H di PipeArgs ke nama DNS perangkat atau alamat IP Anda.

    "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
},

Debug modul Anda dari jarak jauh

  1. Dalam tampilan Debug Visual Studio Code, pilih konfigurasi debug Modul IoT Edge Debug Jarak Jauh (.NET Core).

  2. Pilih Mulai Debug atau pilih F5. Pilih proses yang akan dilampirkan.

  3. Dalam tampilan Debug Visual Studio Code, Anda akan melihat variabel di panel kiri.

  4. Di Visual Studio Code, atur titik henti di modul kustom Anda.

  5. Saat titik henti tertembak, Anda dapat memeriksa variabel, menelusuri kode, dan men-debug modul Anda.

    Cuplikan layar Visual Studio Code yang dilampirkan ke kontainer Docker pada perangkat jarak jauh yang dijeda pada titik henti.

Catatan

Contoh sebelumnya menunjukkan cara men-debug modul IoT Edge pada kontainer jarak jauh. Contoh menambahkan konteks Docker jarak jauh dan perubahan pada hak istimewa Docker pada perangkat jarak jauh. Setelah selesai men-debug modul, atur konteks Docker Anda ke default dan hapus hak istimewa dari akun pengguna Anda.

Lihat entri blog Pengembang IoT ini untuk contoh menggunakan perangkat Raspberry Pi.

Langkah berikutnya

Setelah Anda membuat modul, pelajari cara menyebarkan modul Azure IoT Edge dari Visual Studio Code.

Untuk mengembangkan modul untuk perangkat IoT Edge Anda, pahami dan gunakan SDK Azure IoT Hub.