Tutorial: Mengembangkan modul IoT Edge C# menggunakan kontainer Windows

Artikel
02/28/2022
12 menit untuk membaca

Berlaku untuk: Tepi IoT 1.1

Artikel ini akan menunjukkan cara menggunakan Visual Studio untuk mengembangkan kode C# dan menyebarkannya ke perangkat Windows yang menjalankan Azure IoT Edge.

Catatan

IoT Edge 1.1 LTS adalah saluran rilis terakhir yang mendukung kontainer Windows. Mulai versi 1.2, kontainer Windows tidak lagi didukung. Pertimbangkan untuk menggunakan atau beralih ke IoT Edge untuk Linux di Windows untuk menjalankan IoT Edge di perangkat Windows.

Anda dapat menggunakan modul Azure IoT Edge untuk menyebarkan kode yang mengimplementasikan logika bisnis Anda secara langsung di perangkat IoT Edge. Tutorial ini akan memandu Anda membuat dan menyebarkan modul IoT Edge yang memfilter data sensor.

Dalam tutorial ini, Anda akan mempelajari cara:

Menggunakan Visual Studio untuk membuat modul IoT Edge berdasarkan SDK C#.
Menggunakan Visual Studio dan Docker untuk membuat citra 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 hanya akan mengirim pesan ke upstream jika suhu melebihi ambang batas yang ditentukan. Jenis analisis di tepi ini berguna untuk mengurangi jumlah data yang dikirim ke dan disimpan di cloud.

Jika Anda tidak memiliki langganan Azure, buatlah akun gratis sebelum Anda memulai.

Prasyarat

Tutorial ini menunjukkan cara mengembangkan modul dalam C# menggunakan Visual Studio 2019, lalu menyebarkannya ke perangkat Windows. Jika Anda mengembangkan modul menggunakan kontainer Linux, buka Mengembangkan modul IoT Edge C# menggunakan kontainer Linux sebagai gantinya.

Untuk memahami opsi pengembangan dan penyebaran modul C# menggunakan kontainer Windows, lihat tabel berikut:

C#	Visual Studio Code	Visual Studio 2017 dan 2019
Windows AMD64 develop
Windows AMD64 debug

Sebelum memulai tutorial ini, siapkan lingkungan pengembangan Anda dengan mengikuti petunjuk dalam tutorial Mengembangkan modul IoT Edge menggunakan kontainer Windows. Setelah menyelesaikannya, lingkungan Anda akan berisi prasyarat berikut:

IoT Hub gratis atau standar di Azure.
Perangkat Windows yang menjalankan Azure IoT Edge.
Registri kontainer, seperti Azure Container Registry.
Visual Studio 2019, yang dikonfigurasi dengan ekstensi Azure IoT Edge Tools.
Docker Desktop, yang dikonfigurasi untuk menjalankan kontainer Windows.

Tip

Jika Anda menggunakan Visual Studio 2017 (versi 15.7 atau yang lebih baru), unduh dan pasang Azure IoT Edge Tools untuk Visual Studio 2017 dari Visual Studio Marketplace.

Membuat proyek modul

Di bagian ini, Anda akan membuat proyek modul IoT Edge menggunakan Visual Studio dan ekstensi Azure IoT Edge Tools. Setelah membuat template proyek, Anda akan menambahkan kode baru agar modul memfilter pesan berdasarkan properti yang dilaporkan.

Membuat proyek baru

Azure IoT Edge Tools menyediakan template proyek untuk semua bahasa modul IoT Edge yang didukung di Visual Studio. Template ini memiliki semua file dan kode yang Anda butuhkan untuk menyebarkan modul kerja untuk pengujian IoT Edge. Template ini juga dapat memberi Anda titik awal untuk menyesuaikannya dengan logika bisnis Anda sendiri.

Buka Visual Studio 2019, lalu pilih Buat Proyek Baru.
Pada panel Buat proyek baru, cari IoT Edge, lalu pilih proyek Azure IoT Edge (Windows amd64) dalam daftar hasil.
Pilih Selanjutnya.

Panel Konfigurasi proyek baru Anda akan terbuka.
Pada panel Konfigurasi proyek baru Anda, ganti nama proyek dan solusi menjadi nama yang lebih deskriptif, misalnya CSharpTutorialApp.
Pilih Buat untuk membuat proyek.

Panel Tambahkan Modul akan terbuka.
Pada halaman Konfigurasi proyek Anda, ikuti langkah-langkah berikut ini:

a. Di panel kiri, pilih template Modul C# .
b. Dalam kotak Nama Modul, masukkan CSharpModule.
c. Dalam kotak Url Repositori, ganti localhost:5000 dengan nilai server Login dari registri kontainer Azure Anda, dalam format berikut:

Catatan

Repositori gambar mencakup nama registri kontainer dan nama citra kontainer Anda. Citra kontainer Anda telah diisi dengan nilai nama proyek modul. Anda dapat mengambil server masuk dari halaman ringkasan registri kontainer di portal Azure.
Pilih Tambahkan untuk membuat proyek.

Menambahkan info masuk registri

Manifes penyebaran akan berbagi info masuk registri kontainer Anda dengan runtime IoT Edge. Runtime memerlukan info masuk ini untuk menarik citra privat pribadi Anda di perangkat IoT Edge. Gunakan info masuk dari bagian Kunci akses di registri kontainer Azure Anda.

Di Penjelajah Solusi Visual Studio, buka file deployment.template.json.
Cari properti registryCredentials dalam properti $edgeAgent yang diinginkan. Alamat registri properti akan terisi otomatis dengan informasi yang telah Anda berikan saat membuat proyek. Bidang nama pengguna dan kata sandi harus berisi nama variabel. Contohnya:
```
"registryCredentials": {
  "<registry name>": {
    "username": "$CONTAINER_REGISTRY_USERNAME_<registry name>",
    "password": "$CONTAINER_REGISTRY_PASSWORD_<registry name>",
    "address": "<registry name>.azurecr.io"
  }
}
```
Buka file lingkungan (ENV) di solusi modul Anda. Secara default, file tersembunyi di Penjelajah Solusi, sehingga Anda mungkin perlu memilih tombol Perlihatkan Semua File untuk menampilkannya. File ENV harus berisi variabel nama pengguna dan kata sandi yang sama seperti yang Anda lihat dalam file deployment.template.json.
Tambahkan nilai Nama Pengguna dan Kata Sandi dari registri kontainer Azure Anda.
Simpan perubahan ke file ENV.

Memperbarui modul dengan kode kustom

Kode modul default akan menerima pesan dalam antrean input dan mengirimkannya melalui antrean output. Tambahkan beberapa kode lagi agar modul memproses pesan di tepi sebelum meneruskannya ke hub IoT Anda. Perbarui modul agar modul menganalisis data suhu di setiap pesan dan mengirimkan pesan ke hub IoT hanya jika suhu melebihi ambang batas tertentu.

Di Visual Studio, pilih Program CSharpModule.cs.

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

Tambahkan variabel temperatureThreshold ke kelas Program setelah variabel penghitung. Variabel temperatureThreshold menetapkan nilai yang harus dilampaui oleh suhu yang diukur agar data dapat dikirim ke hub IoT.
```
static int temperatureThreshold { get; set; } = 25;
```

Tambahkan kelas MessageBody, Machine, dan Ambient ke kelas Program setelah pernyataan variabel. 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;}
}

Cari metode Init. Metode ini membuat dan mengonfigurasi objek ModuleClient, yang memungkinkan modul terhubung ke runtime Azure IoT Edge lokal untuk mengirim dan menerima pesan. Kode juga mendaftarkan panggilan balik untuk menerima pesan dari hub IoT Edge melalui titik akhir input1.

Ganti seluruh metode Init dengan kode berikut:
```
static async Task Init()
{
    AmqpTransportSettings amqpSetting = new AmqpTransportSettings(TransportType.Amqp_Tcp_Only);
    ITransportSettings[] settings = { amqpSetting };

    // Open a connection to the Edge runtime.
    ModuleClient ioTHubModuleClient = await ModuleClient.CreateFromEnvironmentAsync(settings);
    await ioTHubModuleClient.OpenAsync();
    Console.WriteLine("IoT Hub module client initialized.");

    // 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.
    await ioTHubModuleClient.SetInputMessageHandlerAsync("input1", FilterMessages, ioTHubModuleClient);
}
```
Metode Init yang diperbarui ini tetap menyiapkan koneksi ke runtime IoT Edge dengan ModuleClient, tetapi juga menambahkan fungsi baru. Ini membaca properti twin modul yang diinginkan untuk mengambil temperatureThreshold. Kemudian membuat panggilan balik yang mendengarkan semua pembaruan mendatang ke properti twin modul yang diinginkan. Dengan panggilan balik ini, Anda dapat memperbarui ambang batas suhu dalam twin modul dari jarak jauh, dan perubahan akan dimasukkan ke dalam modul.

Metode Init yang diperbarui juga mengubah metode SetInputMessageHandlerAsync yang ada. Dalam kode sampel, pesan masuk pada input1 diproses dengan fungsi PipeMessage, tetapi kita ingin mengubahnya untuk menggunakan fungsi FilterMessages yang akan kita buat dalam langkah-langkah berikut.

Tambahkan metode onDesiredPropertiesUpdate baru ke kelas Program. Metode ini menerima pembaruan terkait properti yang diinginkan dari twin modulnya, 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;
}

Hapus contoh metode PipeMessage dan ganti dengan metode FilterMessages baru. Metode ini digunakan setiap kali modul menerima pesan dari hub IoT Edge. Ini memfilter pesan yang melaporkan suhu di bawah ambang suhu yang ditetapkan 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;
    }
}

Simpan file Program.cs.
Buka file deployment.template.json di solusi IoT Edge Anda. File ini memberi tahu agen IoT Edge tentang modul yang akan disebarkan dan memberi tahu hub IoT Edge tentang cara merutekan pesan di antara mereka. Di sini, modul yang akan disebarkan adalah SimulatedTemperatureSensor dan CSharpModule.
Tambahkan twin modul CSharpModule ke manifes penyebaran. Masukkan konten JSON berikut di bagian bawah modulesContent bagian, setelah kembaran modul modulesContent
```
   "CSharpModule": {
       "properties.desired":{
           "TemperatureThreshold":25
       }
   }
```
Simpan file deployment.template.json.

Membangun dan mendorong modul Anda

Di bagian sebelumnya, Anda telah membuat solusi IoT Edge dan menambahkan kode ke CSharpModule untuk memfilter pesan dengan suhu perangkat yang dilaporkan berada di bawah ambang batas yang dapat diterima. Sekarang Anda perlu membangun solusi sebagai gambar kontainer dan mendorongnya ke registri kontainer Anda.

Gunakan perintah berikut untuk masuk ke Docker pada mesin pengembangan Anda. Gunakan 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 Azure.
```
docker login -u <ACR username> -p <ACR password> <ACR login server>
```
Anda mungkin akan menerima peringatan keamanan yang merekomendasikan penggunaan --password-stdin. Meskipun kami merekomendasikannya sebagai praktik terbaik untuk skenario produksi, rekomendasi tersebut di luar cakupan tutorial ini. Untuk informasi selengkapnya, lihat referensi masuk docker.

Membangun dan mendorong

Di Penjelajah Solusi Visual Studio, klik kanan nama proyek yang ingin Anda bangun. Nama defaultnya adalah AzureIotEdgeApp1 dan, karena Anda sedang membangun modul Windows, ekstensinya harus Windows.Amd64.
Pilih Bangun dan Dorong Modul IoT Edge.

Perintah bangun dan dorong akan memulai tiga operasi:
- Pertama, perintah ini akan membuat folder baru dalam solusi bernama config, yang menyimpan seluruh manifes penyebaran. Manifes ini dibangun dari informasi dalam template penyebaran dan file solusi lainnya.
- Kedua, perintah menjalankan docker build untuk membangun citra kontainer, berdasarkan Dockerfile yang sesuai untuk arsitektur target Anda.
- Terakhir, perintah menjalankan docker push untuk mendorong repositori citra ke registri kontainer Anda.
Proses ini mungkin akan memakan waktu beberapa menit saat dijalankan pertama kali, tetapi pada kali berikutnya Anda menjalankan perintah, proses ini akan menjadi lebih cepat.

Menyebarkan modul ke perangkat

Gunakan Visual Studio Cloud Explorer dan ekstensi Azure IoT Edge Tools untuk menyebarkan proyek modul ke perangkat IoT Edge Anda. Anda telah menyiapkan manifes penyebaran untuk skenario Anda, yaitu file deployment.windows-amd64.json dalam folder config. Sekarang Anda hanya perlu memilih perangkat untuk menerima penyebaran.

Pastikan perangkat IoT Edge Anda sudah siap.

Di Visual Studio Cloud Explorer, perluas sumber daya untuk menampilkan daftar perangkat IoT Anda.
Klik kanan nama perangkat IoT Edge penerima penyebaran.
Pilih Buat Penyebaran.
Di Visual Studio File Explorer, pilih file deployment.windows-amd64.json dalam folder config di solusi Anda.
Refresh Cloud Explorer untuk melihat modul yang disebarkan yang tercantum di bawah perangkat Anda.

Melihat data yang dihasilkan

Setelah manifes penyebaran diterapkan di perangkat IoT Edge Anda, runtime IoT Edge pada perangkat akan mengumpulkan informasi penyebaran baru dan mulai mengeksekusinya. Setiap modul yang dijalankan di perangkat tetapi tidak disertakan dalam manifes penyebaran akan dihentikan. Setiap modul yang tidak tersedia di perangkat akan dimulai.

Anda dapat menggunakan ekstensi IoT Edge Tools untuk menampilkan pesan saat pesan masuk di hub IoT.

Di Visual Studio Cloud Explorer, pilih nama perangkat IoT Edge Anda.
Dalam daftar Tindakan, pilih Mulai Pemantauan Titik Akhir Peristiwa Bawaan.
Tampilkan pesan yang masuk di hub IoT Anda. Mungkin diperlukan waktu beberapa saat untuk menerima pesan karena perangkat IoT Edge harus menerima penyebaran barunya dan memulai semua modul. Perubahan pada kode CSharpModule harus menunggu hingga suhu mesin mencapai 25 derajat sebelum pesan dapat dikirim. Kode ini juga menambahkan jenis pesan Pemberitahuan ke setiap pesan yang mencapai ambang batas suhu tersebut.

Mengedit twin modul

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

Di Visual Studio, buka file deployment.windows-amd64.json.

Jangan buka file deployment.template. Jika Anda tidak melihat manifes penyebaran dalam file config di Penjelajah Solusi, pilih ikon Tampilkan semua file di toolbar Penjelajah Solusi.
Cari twin CSharpModule, lalu ubah nilai parameter temperatureThreshold menjadi suhu baru antara 5 hingga 10 derajat lebih tinggi dibandingkan suhu yang dilaporkan terakhir.
Simpan file deployment.windows-amd64.json.
Ikuti lagi petunjuk penyebaran untuk menerapkan manifes penyebaran yang diperbarui ke perangkat Anda.
Pantau pesan perangkat ke cloud yang masuk. Pesan akan berhenti hingga ambang batas suhu baru tercapai.

Membersihkan sumber daya

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

Atau, agar tidak dikenai biaya, Anda dapat menghapus konfigurasi lokal dan sumber daya Azure yang digunakan di sini.

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:

Masuk ke portal Microsoft Azure, lalu pilih Grup sumber daya.
Pilih nama grup sumber daya yang berisi sumber daya pengujian IoT Edge Anda.
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 dengan kode untuk memfilter data mentah yang dibuat oleh perangkat IoT Edge.

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

Azure Functions Azure Stream Analytics Azure Machine Learning Layanan Custom Vision