Tutorial: Mengembangkan modul IoT Edge C# menggunakan kontainer Linux

  • Artikel
  • 12 menit untuk membaca

Berlaku untuk tandacentang:IoT Edge 1.1 IoT Edge 1.1 IoT Edge 1.2 tanda centang IoT Edge 1.2 IoT Edge 1.3 IoT Edge 1.3

Gunakan Visual Studio Code untuk mengembangkan kode C# dan menyebarkannya ke perangkat yang menjalankan Azure IoT Edge.

Anda dapat menggunakan modul Azure IoT Edge untuk menyebarkan kode yang menerapkan logika bisnis langsung ke perangkat IoT Edge. Tutorial ini akan memandu Anda membuat dan menyebarkan modul IoT Edge yang memfilter data sensor. Anda menggunakan perangkat IoT Edge yang disimulasikan yang dibuat di mulai cepat. Dalam tutorial ini, Anda akan mempelajari cara:

  • Menggunakan Visual Studio Code untuk membuat modul IoT Edge berdasarkan .NET Core 2.1 SDK.
  • Menggunakan Visual Studio Code dan Docker untuk membuat gambar Docker dan menerbitkannya ke registri Anda.
  • Menyebarkan modul ke perangkat IoT Edge Anda.
  • Menampilkan data yang dibuat.

Modul IoT Edge yang dibuat dalam tutorial ini akan memfilter data suhu yang dihasilkan oleh perangkat Anda. Modul ini hanya mengirim pesan ke upstream jika suhu di atas ambang batas yang ditentukan. Jenis analisis di tepi ini berguna untuk mengurangi jumlah data yang dikomunikasikan dan disimpan di cloud.

Jika Anda tidak memiliki Langganan Azure, buat Akun gratis Azure sebelum memulai.

Prasyarat

Tutorial ini menunjukkan cara mengembangkan modul di C# menggunakan Visual Studio Code, dan menyebarkannya ke perangkat IoT Edge. Jika Anda mengembangkan modul menggunakan kontainer Windows, buka Mengembangkan modul IoT Edge C# menggunakan kontainer Windows sebagai gantinya.

Gunakan tabel berikut untuk memahami opsi Anda untuk mengembangkan dan menyebarkan modul C# menggunakan kontainer Linux:

C# Visual Studio Code Visual Studio
Linux AMD64 Modul C# untuk LinuxAMD64 di VS Code Modul C# untuk LinuxAMD64 di Visual Studio
Linux ARM32 Modul C# untuk LinuxARM32 di VS Code Modul C# untuk LinuxARM32 di Visual Studio
Linux ARM64 Modul C# untuk LinuxARM64 di Visual Studio Code Modul C# untuk LinuxARM64 di Visual Studio

Sebelum memulai tutorial ini, Anda harus menyelesaikan tutorial sebelumnya untuk menyiapkan lingkungan pengembangan, Mengembangkan modul IoT Edge menggunakan kontainer Linux. Setelah menyelesaikan tutorial tersebut, Anda akan memiliki prasyarat berikut:

Untuk menyelesaikan tutorial ini, siapkan prasyarat tambahan berikut di komputer pengembangan Anda:

Membuat proyek modul

Langkah-langkah berikut membuat proyek modul IoT Edge untuk C# dengan menggunakan Visual Studio Code dan ekstensi Azure IoT Tools. Setelah membuat templat proyek, tambahkan kode baru agar modul memfilter pesan berdasarkan properti yang dilaporkan.

Membuat proyek baru

Buat templat solusi C# yang dapat Anda sesuaikan dengan kode Anda sendiri.

  1. Di Visual Studio Code, pilih Tampilan>Palet Perintah untuk membuka palet perintah Visual Studio Code.

  2. Di palet perintah, masukkan dan jalankan perintah Azure: Masuk dan ikuti instruksi untuk masuk ke akun Azure Anda. Jika Anda sudah masuk, Anda bisa melewati langkah ini.

  3. Di palet perintah, masukkan dan jalankan perintah Azure IoT Edge: Solusi IoT Edge baru. Ikuti perintah di palet perintah untuk membuat solusi Anda.

    Bidang Nilai
    Memilih folder Pilih lokasi di komputer pengembangan Anda untuk Visual Studio Code guna membuat file solusi.
    Memberikan nama solusi Masukkan nama deskriptif untuk solusi Anda atau terima EdgeSolution default.
    Memilih templat modul Pilih Modul C# .
    Memberi nama modul Beri nama CSharpModule modul Anda.
    Memberikan repositori gambar Docker untuk modul tersebut Repositori gambar menyertakan nama registri kontainer dan nama gambar kontainer Anda. Gambar kontainer Anda sudah terisi dari nama yang Anda berikan pada langkah terakhir. Ganti localhost:5000 dengan nilai Server masuk dari registri kontainer Azure Anda. Anda dapat mengambil Server masuk dari halaman Gambaran umum registri kontainer di portal Azure.

    Repositori gambar akhir terlihat seperti <nama> registri.azurecr.io/csharpmodule.

    Menyediakan repositori gambar Docker

Menambahkan informasi masuk registri

File lingkungan menyimpan informasi masuk untuk repositori kontainer Anda dan membagikannya dengan runtime Azure IoT Edge. Runtime memerlukan info masuk ini untuk menarik gambar privat Anda ke perangkat IoT Edge. Gunakan info masuk dari bagian Kunci akses registri kontainer Azure Anda.

Ekstensi IoT Edge mencoba menarik info masuk registri kontainer dari Azure dan mengisinya dalam file lingkungan. Periksa untuk melihat apakah info masuk Anda sudah disertakan. Jika belum, tambahkan sekarang:

  1. Di penjelajah VS Code, buka file .env.
  2. Perbarui bidang dengan nilai nama pengguna dan kata sandi dari registri kontainer Azure.
  3. Simpan file ini.

Catatan

Tutorial ini menggunakan kredensial masuk admin untuk Azure Container Registry, yang memudahkan pengembangan dan pengujian skenario. Saat Anda siap untuk skenario produksi, kami merekomendasikan opsi autentikasi dengan hak paling rendah seperti perwakilan layanan. Untuk informasi selengkapnya, lihat Mengelola akses ke registri kontainer Anda.

Memilih arsitektur target Anda

Saat ini, Visual Studio Code dapat mengembangkan modul C# untuk perangkat Linux AMD64 dan Linux ARM32v7. Anda harus memilih arsitektur mana yang ditargetkan dengan setiap solusi, karena kontainer dibuat dan dijalankan secara berbeda untuk setiap jenis arsitektur. Default-nya adalah Linux AMD64.

  1. Buka palet perintah dan cari Azure IoT Edge: Atur Platform Target Default untuk Solusi Edge, atau pilih ikon pintasan di bilah samping di bagian bawah jendela.

  2. Di palet perintah, pilih arsitektur target dari daftar opsi. Untuk tutorial ini, gunakan komputer virtual Ubuntu sebagai perangkat IoT Edge, untuk menjaga amd64 tetap sebagai default.

Memperbarui modul dengan kode kustom

  1. Di penjelajah VS Code, buka modules>CSharpModule>Program.cs.

  2. Di bagian atas namespace layanan CSharpModule, tambahkan tiga pernyataan menggunakan untuk jenis yang digunakan nanti:

    using System.Collections.Generic;     // For KeyValuePair<>
using Microsoft.Azure.Devices.Shared; // For TwinCollection
using Newtonsoft.Json;                // For JsonConvert

  3. Tambahkan variabel temperatureThreshold ke kelas Program. Variabel ini menetapkan nilai ambang suhu yang diukur untuk data yang akan dikirim ke hub IoT Anda.

    static int temperatureThreshold { get; set; } = 25;

  4. Tambahkan kelas MessageBody, Machine, dan Ambient ke kelas Program. Kelas ini menentukan skema yang diharapkan untuk isi pesan masuk.

    class MessageBody
{
    public Machine machine {get;set;}
    public Ambient ambient {get; set;}
    public string timeCreated {get; set;}
}
class Machine
{
    public double temperature {get; set;}
    public double pressure {get; set;}
}
class Ambient
{
    public double temperature {get; set;}
    public int humidity {get; set;}
}

  5. Temukan fungsi Init. Metode ini membuat dan mengonfigurasi objek ModuleClient, yang memungkinkan modul tersambung ke runtime Azure IoT Edge lokal untuk mengirim dan menerima pesan. Setelah membuat ModuleClient, kode membaca nilai temperatureThreshold dari properti yang diinginkan twin modul. Kode tersebut juga mendaftarkan panggilan balik untuk menerima pesan dari hub Azure IoT Edge melalui titik akhir yang bernama input1.

    Ganti metode SetInputMessageHandlerAsync dengan metode yang baru yang memperbarui nama titik akhir dan metode yang dipanggil saat input tiba. Selain itu, tambahkan metode SetDesiredPropertyUpdateCallbackAsync untuk pembaruan ke properti yang diinginkan. Untuk melakukan perubahan ini, ganti baris terakhir metode Init dengan kode berikut:

    // Register a callback for messages that are received by the module.
// await ioTHubModuleClient.SetInputMessageHandlerAsync("input1", PipeMessage, iotHubModuleClient);

// Read the TemperatureThreshold value from the module twin's desired properties
var moduleTwin = await ioTHubModuleClient.GetTwinAsync();
await OnDesiredPropertiesUpdate(moduleTwin.Properties.Desired, ioTHubModuleClient);

// Attach a callback for updates to the module twin's desired properties.
await ioTHubModuleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertiesUpdate, null);

// Register a callback for messages that are received by the module. Messages received on the inputFromSensor endpoint are sent to the FilterMessages method.
await ioTHubModuleClient.SetInputMessageHandlerAsync("inputFromSensor", FilterMessages, ioTHubModuleClient);

  6. Tambahkan metode onDesiredPropertiesUpdate ke kelas Program. Metode ini menerima pembaruan terkait properti yang diinginkan dari twin modul, dan memperbarui variabel temperatureThreshold agar sesuai. Semua modul memiliki twin modulnya masing-masing, yang memungkinkan Anda mengonfigurasi kode yang berjalan di dalam modul langsung dari cloud.

    static Task OnDesiredPropertiesUpdate(TwinCollection desiredProperties, object userContext)
{
    try
    {
        Console.WriteLine("Desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));

        if (desiredProperties["TemperatureThreshold"]!=null)
            temperatureThreshold = desiredProperties["TemperatureThreshold"];

    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error when receiving desired property: {0}", exception);
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error when receiving desired property: {0}", ex.Message);
    }
    return Task.CompletedTask;
}

  7. Ganti metode PipeMessage dengan metode FilterMessages. Metode ini dipanggil setiap kali modul menerima pesan dari hub IoT Edge. Ini memfilter pesan yang melaporkan suhu di bawah ambang yang diatur melalui twin modul. Metode ini juga menambahkan properti MessageType ke pesan dengan nilai yang diatur ke Pemberitahuan.

    static async Task<MessageResponse> FilterMessages(Message message, object userContext)
{
    var counterValue = Interlocked.Increment(ref counter);
    try
    {
        ModuleClient moduleClient = (ModuleClient)userContext;
        var messageBytes = message.GetBytes();
        var messageString = Encoding.UTF8.GetString(messageBytes);
        Console.WriteLine($"Received message {counterValue}: [{messageString}]");

        // Get the message body.
        var messageBody = JsonConvert.DeserializeObject<MessageBody>(messageString);

        if (messageBody != null && messageBody.machine.temperature > temperatureThreshold)
        {
            Console.WriteLine($"Machine temperature {messageBody.machine.temperature} " +
                $"exceeds threshold {temperatureThreshold}");
            using (var filteredMessage = new Message(messageBytes))
            {
                foreach (KeyValuePair<string, string> prop in message.Properties)
                {
                    filteredMessage.Properties.Add(prop.Key, prop.Value);
                }

                filteredMessage.Properties.Add("MessageType", "Alert");
                await moduleClient.SendEventAsync("output1", filteredMessage);
            }
        }

        // Indicate that the message treatment is completed.
        return MessageResponse.Completed;
    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", exception);
        }
        // Indicate that the message treatment is not completed.
        var moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
        // Indicate that the message treatment is not completed.
        ModuleClient moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
}

  8. Simpan file Program.cs.

  9. Di penjelajah VS Code, buka file deployment.template.json di ruang kerja solusi IoT Edge Anda.

  10. Karena kita mengubah nama titik akhir yang didengarkan oleh modul, kita juga perlu memperbarui rute pada manifes penyebaran agar edgeHub dapat mengirim pesan ke titik akhir yang baru.

    Temukan bagian rute di modul kembar $edgeHub. Perbarui rute sensorToCSharpModule untuk mengganti input1 dengan inputFromSensor:

    "sensorToCSharpModule": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/CSharpModule/inputs/inputFromSensor\")"

  11. Tambahkan twin modul CSharpModule ke manifes penyebaran. Sisipkan konten JSON berikut di bawah bagian moduleContent, setelah twin modul $edgeHub:

       "CSharpModule": {
       "properties.desired":{
           "TemperatureThreshold":25
       }
   }

    Menambahkan twin modul ke templat penyebaran

  12. Simpan file deployment.template.json.

Membuat dan mendorong modul Anda

Di bagian sebelumnya, Anda membuat solusi IoT Edge dan menambahkan kode ke CSharpModule. Kode baru memfilter pesan tempat suhu komputer yang dilaporkan berada dalam batas yang dapat diterima. Sekarang, Anda perlu membuat solusi sebagai gambar kontainer dan mendorongnya ke registri kontainer Anda.

  1. Buka terminal terintegrasi Visual Studio Code dengan memilih Tampilan>Terminal.

  2. Masuk ke Docker dengan memasukkan perintah berikut di terminal. Masuk menggunakan nama pengguna, kata sandi, dan server masuk dari registri kontainer Azure Anda. Anda dapat mengambil nilai ini dari bagian Kunci akses registri Anda di portal Microsoft Azure.

    docker login -u <ACR username> -p <ACR password> <ACR login server>

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

  3. Di penjelajah Visual Studio Code, klik kanan file deployment.template.json, lalu pilih Bangun dan Dorong Solusi IoT Edge.

    Perintah bangun dan kirim akan memulai tiga operasi. Pertama, perintah ini membuat folder baru dalam solusi yang disebut konfigurasi yang menyimpan manifes penyebaran penuh, yang dibangun dari informasi dalam templat penyebaran dan file solusi lainnya. Kedua, perintah ini menjalankan docker build untuk membangun gambar kontainer berdasarkan dockerfile yang sesuai untuk arsitektur target Anda. Kemudian, perintah ini menjalankan docker push untuk mendorong repositori gambar ke registri kontainer Anda.

    Proses ini mungkin akan memakan waktu beberapa menit saat dijalankan pertama kali, tetapi lebih cepat pada kali berikutnya saat Anda menjalankan perintah.

Menyebarkan dan menjalankan solusi

Gunakan penjelajah Visual Studio Code dan ekstensi Azure IoT Tools untuk menyebarkan proyek modul ke perangkat IoT Edge Anda. Anda sudah memiliki manifes penyebaran yang disiapkan untuk skenario, file deployment.amd64.js di folder konfigurasi. Sekarang Anda hanya perlu memilih perangkat untuk menerima penyebaran.

Pastikan perangkat Azure IoT Edge Anda sudah siap dan dapat dijalankan.

  1. Di penjelajah Visual Studio Code, pada bagian Azure IoT Hub, luaskan Perangkat untuk melihat daftar perangkat IoT Anda.

  2. Klik kanan nama perangkat Azure IoT Edge, lalu pilih Buat Penyebaran untuk Perangkat Tunggal.

  3. Pilih file deployment.amd64.json di folder config, lalu klik Pilih Manifes Penyebaran Azure Stack Edge. Jangan gunakan file deployment.template.json.

  4. Pada perangkat Anda, luaskan Modul untuk melihat daftar modul yang disebarkan dan berjalan. Klik tombol refresh. Anda akan melihat CSharpModule baru berjalan bersama dengan modul SimulatedTemperatureSensor serta $edgeAgent dan $edgeHub.

    Mungkin perlu waktu beberapa menit untuk memulai modul. Runtime IoT Edge perlu menerima manifes penyebaran barunya, menarik gambar modul dari runtime kontainer, lalu memulai setiap modul baru.

Menampilkan data yang dihasilkan

Setelah menerapkan manifes penyebaran di perangkat IoT Edge Anda, runtime IoT Edge di perangkat akan mengumpulkan informasi penyebaran baru dan mulai menjalankannya. Setiap modul yang berjalan di perangkat yang tidak disertakan dalam manifes penyebaran akan dihentikan. Setiap modul yang tidak tersedia di perangkat akan dimulai.

  1. Di penjelajah Visual Studio Code, klik kanan nama perangkat IoT Edge, lalu pilih Mulai Pemantauan Titik Akhir Peristiwa Bawaan.

  2. Tampilkan pesan yang masuk di IoT Hub Anda. Mungkin diperlukan waktu beberapa saat untuk menerima pesan karena perangkat IoT Edge harus menerima penyebaran barunya dan memulai semua modul. Lalu, perubahan yang dilakukan di kode CModule menunggu sampai suhu komputer mencapai 25 derajat sebelum mengirim pesan. Kode ini juga menambahkan jenis pesan Pemberitahuan ke setiap pesan yang mencapai ambang suhu tersebut.

    Menampilkan pesan yang tiba di IoT Hub

Mengedit twin modul

Kami menggunakan twin modul CSharpModule dalam manifes penyebaran untuk mengatur ambang suhu pada 25 derajat. Anda dapat menggunakan twin modul untuk mengubah fungsionalitas tanpa perlu memperbarui kode modul.

  1. Di Visual Studio Code, perluas detail di bawah perangkat IoT Edge Anda untuk melihat modul yang berjalan.

  2. Klik kanan CSharpModule, lalu pilih Edit twin modul.

  3. Cari TemperatureThreshold di properti yang diinginkan. Ubah nilainya ke suhu baru, 5 derajat hingga 10 derajat lebih tinggi dari suhu terbaru yang dilaporkan.

  4. Simpan file twin modul.

  5. Klik kanan di mana saja di panel pengeditan twin modul, lalu pilih Perbarui twin modul.

  6. Pantau pesan perangkat ke cloud yang masuk. Anda akan melihat pesan berhenti hingga ambang suhu baru tercapai.

Membersihkan sumber daya

Jika berencana untuk melanjutkan ke artikel yang disarankan berikutnya, Anda dapat menyimpan sumber daya dan konfigurasi yang Anda buat dan menggunakannya kembali. Anda juga dapat tetap menggunakan perangkat Azure IoT Edge yang sama sebagai perangkat uji.

Jika tidak, Anda dapat menghapus konfigurasi lokal dan sumber daya Azure yang Anda gunakan dalam artikel ini untuk menghindari tagihan.

Menghapus sumber daya Azure

Menghapus sumber daya Azure dan grup sumber daya tidak dapat diubah. Pastikan Anda tidak menghapus grup sumber daya atau sumber daya yang salah secara tidak sengaja. Jika Anda membuat hub IoT di dalam grup sumber daya yang sudah ada yang berisi sumber daya yang ingin Anda simpan, hapus hanya sumber daya hub IoT itu sendiri, bukan grup sumber daya.

Untuk menghapus sumber daya:

  1. Masuk ke portal Microsoft Azure, lalu pilih Grup sumber daya.

  2. Pilih nama grup sumber daya yang berisi sumber daya pengujian IoT Edge Anda.

  3. Tinjau daftar sumber daya yang terdapat dalam grup sumber daya Anda. Jika ingin menghapus semuanya, Anda dapat memilih Hapus grup sumber daya. Jika hanya ingin menghapus beberapa sumber daya, Anda dapat mengklik setiap sumber daya untuk menghapusnya satu per satu.

Langkah berikutnya

Dalam tutorial ini, Anda telah membuat modul IoT Edge yang berisi kode untuk memfilter data mentah yang dibuat oleh perangkat IoT Edge.

Anda dapat melanjutkan ke tutorial berikutnya, untuk mempelajari bagaimana Azure IoT Edge dapat membantu Anda menyebarkan layanan cloud Azure untuk memproses dan menganalisis data di tepi.

FungsiAnalisis AliranAzure Machine LearningLayanan Visual Kustom