Een C# IoT Edge-module ontwikkelen om bestanden te verplaatsen met Azure Stack Edge Pro FPGA

Artikel
02/27/2024

Belangrijk

Azure Stack Edge Pro FPGA-apparaten zullen in februari 2024 het einde van de levensduur bereiken. Als u nieuwe implementaties overweegt, raden we u aan Om Azure Stack Edge Pro 2- of Azure Stack Edge Pro GPU-apparaten voor uw workloads te verkennen.

In dit artikel wordt uitgelegd hoe u een IoT Edge-module maakt voor implementatie met uw Azure Stack Edge Pro FPGA-apparaat. Azure Stack Edge Pro FPGA is een opslagoplossing waarmee u gegevens kunt verwerken en verzenden via een netwerk naar Azure.

U kunt Azure IoT Edge-modules gebruiken met uw Azure Stack Edge Pro FPGA om de gegevens te transformeren terwijl deze naar Azure zijn verplaatst. De module die in dit artikel wordt gebruikt, implementeert de logica voor het kopiëren van een bestand van een lokale share naar een cloudshare op uw Azure Stack Edge Pro FPGA-apparaat.

In dit artikel leert u het volgende:

Maak een containerregister om uw modules (Docker-installatiekopieën) op te slaan en te beheren.
Maak een IoT Edge-module om te implementeren op uw Azure Stack Edge Pro FPGA-apparaat.

Over de IoT Edge-module

Uw Azure Stack Edge Pro FPGA-apparaat kan IoT Edge-modules implementeren en uitvoeren. Edge-modules zijn in wezen Docker-containers die een specifieke taak uitvoeren, zoals het opnemen van een bericht van een apparaat, het transformeren van een bericht of het verzenden van een bericht naar een IoT Hub. In dit artikel maakt u een module waarmee bestanden van een lokale share worden gekopieerd naar een cloudshare op uw Azure Stack Edge Pro FPGA-apparaat.

Bestanden worden naar de lokale share geschreven op uw Azure Stack Edge Pro FPGA-apparaat.
De bestands gebeurtenisgenerator maakt een bestands gebeurtenis voor elk bestand dat naar de lokale share is geschreven. De bestandsevenementen worden ook gegenereerd wanneer een bestand wordt gewijzigd. De bestandsevenementen worden vervolgens verzonden naar IoT Edge Hub (in IoT Edge-runtime).
De aangepaste IoT Edge-module verwerkt de bestands gebeurtenis om een bestands gebeurtenisobject te maken dat ook een relatief pad voor het bestand bevat. De module genereert een absoluut pad met behulp van het relatieve bestandspad en kopieert het bestand van de lokale share naar de cloudshare. De module verwijdert vervolgens het bestand uit de lokale share.

Hoe de Azure IoT Edge-module werkt in Azure Stack Edge Pro FPGA

Zodra het bestand zich in de cloudshare bevindt, wordt het automatisch geüpload naar uw Azure Storage-account.

Vereisten

Zorg ervoor dat u voordat u begint de volgende zaken paraat hebt:

Een Azure Stack Edge Pro FPGA-apparaat dat wordt uitgevoerd.
- Het apparaat heeft ook een bijbehorende IoT Hub-resource.
- Op het apparaat is een Edge-rekenrol geconfigureerd. Ga voor meer informatie naar Compute configureren voor uw Azure Stack Edge Pro FPGA.
De volgende ontwikkelbronnen:
- Visual Studio Code.
- De extensie C# voor Visual Studio Code (van OmniSharp).
- Azure IoT Edge-extensie voor Visual Studio Code.
- .NET Core 2.1 SDK.
- Docker CE. Mogelijk moet u een account maken om de software te downloaden en te installeren.

Een containerregister maken

Een Azure-containerregister is een persoonlijk Docker-register in Azure waar u uw persoonlijke installatiekopieën van de Docker-container kunt opslaan en beheren. De twee populaire Docker-registerservices die beschikbaar zijn in de cloud zijn Azure Container Registry en Docker Hub. In dit artikel wordt het Container Registry gebruikt.

Vanuit een browser kunt u zich aanmelden bij Azure Portal.
Selecteer Een containerregister >voor containers > maken. Klik op Create.
Geef op:
1. Een unieke registernaam in Azure die 5 tot 50 alfanumerieke tekens bevat.
2. Kies een Abonnement.
3. Maak een nieuwe resourcegroep of kies een bestaande resourcegroep.
4. Selecteer een Locatie. We raden u aan deze locatie hetzelfde te maken als die is gekoppeld aan de Azure Stack Edge-resource.
5. Stel de Gebruiker met beheerdersrechten in op Inschakelen.
6. Stel de SKU in op Basic.
Selecteer Maken.
Nadat het containerregister is gemaakt, bladert u ernaartoe en selecteert u Toegangssleutels.
Kopieer de waarden voor Aanmeldingsserver, Gebruikersnaam en wachtwoord. U gebruikt deze waarden later om de Docker-installatiekopieën naar uw register te publiceren en de registerreferenties toe te voegen aan de Azure IoT Edge-runtime.

Een IoT Edge-moduleproject creëren

Met de volgende stappen maakt u een IoT Edge-moduleproject op basis van de .NET Core 2.1 SDK. Het project maakt gebruik van Visual Studio Code en de Azure IoT Edge-extensie.

Een nieuwe oplossing maken

Maak een C#-oplossingssjabloon die u met uw eigen code kunt aanpassen.

Selecteer in Visual Studio Code het opdrachtenpalet weergeven > om het opdrachtenpalet van VS Code te openen.
Voer in het opdrachtpalet de opdracht Azure: Sign in in en voer deze uit. Volg vervolgens de instructies om u aan te melden bij uw Azure-account. Als u al bent aangemeld, kunt u deze stap overslaan.
Voer in het opdrachtpalet de opdracht Azure IoT Edge: New IoT Edge solution in en voer deze uit. Geef in het opdrachtpalet de volgende informatie op om de oplossing te maken:
1. Selecteer de map waarin u de oplossing wilt maken.
2. Geef een naam op voor de oplossing of houd de standaardnaam EdgeSolution aan.
3. Kies C# Module als de modulesjabloon.
4. Vervang de standaardmodulenaam door de naam die u wilt toewijzen, in dit geval FileCopyModule.
5. Geef het containerregister op dat u in de vorige sectie hebt gemaakt als de opslagplaats voor installatiekopieën voor uw eerste module. Vervang localhost:5000 door de gekopieerde waarde voor de aanmeldingsserver.
  
  De uiteindelijke tekenreeks ziet er als <Login server name>/<Module name>volgt uit. In dit voorbeeld is de tekenreeks: mycontreg2.azurecr.io/filecopymodule.
Ga naar de map Bestand > openen.
Blader en wijs de Map EdgeSolution aan die u eerder hebt gemaakt. In het VS Code-venster wordt uw Werkruimte van uw IoT Edge-oplossing geladen met de vijf onderdelen op het hoogste niveau. U bewerkt de map .vscode , het .gitignore-bestand , het .env-bestand en de deployment.template.json in dit artikel niet.

Het enige onderdeel dat u wijzigt, is de map modules. Deze map bevat de C#-code voor uw module en Docker-bestanden om uw module te bouwen als een containerinstallatiekopieën.

De module bijwerken met aangepaste code

Open in VS Code Explorer modules > FileCopyModule > Program.cs.
Voeg bovenaan de FileCopyModule-naamruimte het volgende toe met behulp van instructies voor typen die later worden gebruikt. Microsoft.Azure.Devices.Client.Transport.Mqtt is een protocol voor het verzenden van berichten naar IoT Edge Hub.
```
namespace FileCopyModule
{
    using Microsoft.Azure.Devices.Client.Transport.Mqtt;
    using Newtonsoft.Json;
```

Voeg de variabele InputFolderPath en OutputFolderPath toe aan de klasse Program.

class Program
    {
        static int counter;
        private const string InputFolderPath = "/home/input";
        private const string OutputFolderPath = "/home/output";

Voeg direct na de vorige stap de klasse FileEvent toe om de berichttekst te definiëren.

/// <summary>
/// The FileEvent class defines the body of incoming messages. 
/// </summary>
private class FileEvent
{
    public string ChangeType { get; set; }

    public string ShareRelativeFilePath { get; set; }

    public string ShareName { get; set; }
}

In de methode Init wordt met de code een object ModuleClient gemaakt en geconfigureerd. Met dit object kan de module verbinding maken met de lokale Azure IoT Edge-runtime met behulp van het MQTT-protocol om berichten te verzenden en te ontvangen. De verbindingsreeks die in de methode Init wordt gebruikt, wordt door de IoT Edge-runtime aan de module geleverd. Met de code wordt een FileCopy-callback geregistreerd voor het ontvangen van berichten van een IoT Edge-hub via het invoer1-eindpunt . Vervang de Init-methode door de volgende code.

/// <summary>
/// Initializes the ModuleClient and sets up the callback to receive
/// messages containing file event information
/// </summary>
static async Task Init()
{
    MqttTransportSettings mqttSetting = new MqttTransportSettings(TransportType.Mqtt_Tcp_Only);
    ITransportSettings[] settings = { mqttSetting };

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

    // Register callback to be called when a message is received by the module
    await ioTHubModuleClient.SetInputMessageHandlerAsync("input1", FileCopy, ioTHubModuleClient);
}

Verwijder de code voor de PipeMessage-methode en voeg de code voor FileCopy in.

    /// <summary>
    /// This method is called whenever the module is sent a message from the IoT Edge Hub.
    /// This method deserializes the file event, extracts the corresponding relative file path, and creates the absolute input file path using the relative file path and the InputFolderPath.
    /// This method also forms the absolute output file path using the relative file path and the OutputFolderPath. It then copies the input file to output file and deletes the input file after the copy is complete.
    /// </summary>
    static async Task<MessageResponse> FileCopy(Message message, object userContext)
    {
        int counterValue = Interlocked.Increment(ref counter);

        try
        {
            byte[] messageBytes = message.GetBytes();
            string messageString = Encoding.UTF8.GetString(messageBytes);
            Console.WriteLine($"Received message: {counterValue}, Body: [{messageString}]");

            if (!string.IsNullOrEmpty(messageString))
            {
                var fileEvent = JsonConvert.DeserializeObject<FileEvent>(messageString);

                string relativeFileName = fileEvent.ShareRelativeFilePath.Replace("\\", "/");
                string inputFilePath = InputFolderPath + relativeFileName;
                string outputFilePath = OutputFolderPath + relativeFileName;

                if (File.Exists(inputFilePath))                
                {
                    Console.WriteLine($"Moving input file: {inputFilePath} to output file: {outputFilePath}");
                    var outputDir = Path.GetDirectoryName(outputFilePath);
                    if (!Directory.Exists(outputDir))
                    {
                        Directory.CreateDirectory(outputDir);
                    }

                    File.Copy(inputFilePath, outputFilePath, true);
                    Console.WriteLine($"Copied input file: {inputFilePath} to output file: {outputFilePath}");
                    File.Delete(inputFilePath);
                    Console.WriteLine($"Deleted input file: {inputFilePath}");
                } 
                else
                {
                    Console.WriteLine($"Skipping this event as input file doesn't exist: {inputFilePath}");   
                }
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine("Caught exception: {0}", ex.Message);
            Console.WriteLine(ex.StackTrace);
        }

        Console.WriteLine($"Processed event.");
        return MessageResponse.Completed;
    }

Sla dit bestand op.
U kunt ook een bestaand codevoorbeeld voor dit project downloaden. Vervolgens kunt u het bestand valideren dat u hebt opgeslagen op basis van het program.cs-bestand in dit voorbeeld.

Uw IoT Edge-oplossing bouwen

In de vorige sectie hebt u een IoT Edge-oplossing gemaakt en code toegevoegd aan de FileCopyModule om bestanden van lokale share naar de cloudshare te kopiëren. Nu moet u de oplossing bouwen als een containerinstallatiekopie en deze naar het containerregister pushen.

Ga in VSCode naar Terminal > New Terminal om een nieuwe geïntegreerde Visual Studio Code-terminal te openen.
Meld u aan bij Docker door de volgende opdracht in te voeren in de geïntegreerde terminal.

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

Gebruik de aanmeldingsserver en gebruikersnaam die u hebt gekopieerd uit het containerregister.
Wanneer u wordt gevraagd om een wachtwoord, geeft u het wachtwoord op. U kunt ook de waarden voor aanmeldingsserver, gebruikersnaam en wachtwoord ophalen uit de toegangssleutels in uw containerregister in Azure Portal.
Zodra de referenties zijn opgegeven, kunt u de module-installatiekopieën naar uw Azure-containerregister pushen. Klik in VS Code Explorer met de rechtermuisknop op het module.json-bestand en selecteer De oplossing Build en Push IoT Edge.

Wanneer u Visual Studio Code vertelt om uw oplossing te bouwen, worden er twee opdrachten uitgevoerd in de geïntegreerde terminal: docker build en docker push. Met deze twee opdrachten wordt uw code gebouwd, wordt de CSharpModule.dll in een container opgeslagen en wordt de code vervolgens naar het containerregister gepusht dat u hebt opgegeven toen u de oplossing initialiseerde.

U wordt gevraagd het moduleplatform te kiezen. Selecteer amd64 die overeenkomt met Linux.

Belangrijk

Alleen de Linux-modules worden ondersteund.

Mogelijk ziet u de volgende waarschuwing die u kunt negeren:

Program.cs(77.44): waarschuwing CS1998: Deze asynchrone methode mist 'await'-operators en wordt synchroon uitgevoerd. Overweeg het gebruik van de operator 'await' om niet-blokkerende API-aanroepen te wachten of 'await Task.Run(...)' om CPU-gebonden werkzaamheden uit te voeren op een achtergrondthread.
U kunt het volledige adres van de containerinstallatiekopie, inclusief de tag, zien in de geïntegreerde terminal van VS Code. Het adres van de installatiekopie is opgebouwd uit informatie die zich in het module.json-bestand bevindt met de indeling <repository>:<version>-<platform>. Voor dit artikel moet het er als mycontreg2.azurecr.io/filecopymodule:0.0.1-amd64volgt uitzien.