Entwickeln Sie benutzerdefinierte .NET Standard-Funktionen für Azure Stream Analytics-Jobs (eingestellt)

Azure Stream Analytics bietet eine SQL-ähnliche Abfragesprache zum Ausführen von Transformationen und Berechnungen über Datenströme von Ereignisdaten. Die Sprache enthält viele integrierte Funktionen, aber einige komplexe Szenarien erfordern mehr Flexibilität. Durch die Verwendung von .NET Standard user-defined functions (UDF) können Sie eigene Funktionen aufrufen, die in jeder .NET Standard-Sprache geschrieben sind (zum Beispiel C# oder F#), um die Stream Analytics Abfragesprache zu erweitern. Verwenden Sie UDFs für komplexe mathematische Berechnungen, importieren Sie benutzerdefinierte ML-Modelle mit ML.NET und verwenden Sie benutzerdefinierte Imputationslogik für fehlende Daten.

Da diese Funktion eingestellt ist, nutzen Sie diesen Artikel, um zu verstehen, wie .NET Standard UDFs funktionierten und um Ihre Migration zu benutzerdefinierten JavaScript-Funktionen zu planen.

Informationen zu benutzerdefinierten Funktionen für .NET Standard

.NET Standard UDFs erweitern die Stream Analytics Abfragesprache mit benutzerdefinierter Logik. Bevor du ein UDF baust, überprüfe die Regionen, in denen das Feature ausgeführt wird, den verwendeten Paketpfad, die unterstützten Typzuordnungen und die Feature-Einschränkungen.

Azure Stream Analytics unterstützt das Feature für benutzerdefinierte .NET-Funktionen für Cloud-Jobs, die auf Stream-Analytics-Clustern ausgeführt werden. Jobs, die auf der Standard-Multitenant-SKU laufen, können diese Funktion in den folgenden öffentlichen Regionen nutzen:

• Zentraler Westen der USA
• Nordeuropa
• East US
• West US
• Ost-USA 2
• West Europe

Um diese Funktion in einer anderen Region zu nutzen, fordern Sie den Zugriff an.

Das Format eines beliebigen UDF-Pakets weist den Pfad /UserCustomCode/CLR/*auf. Azure Stream Analytics kopiert dynamische Linkbibliotheken (DLLs) und Ressourcen unter dem /UserCustomCode/CLR/* Ordner, was hilft, Benutzer-DLLs von System- und Azure Stream Analytics-DLLs zu isolieren. Alle Funktionen verwenden diesen Paketpfad, unabhängig davon, wie Sie sie einsetzen.

Damit Azure Stream Analytics-Werte in C# verwendet werden können, müssen sie zwischen den Umgebungen übertragen werden. Marshaling erfolgt für alle Eingabeparameter einer UDF. Jeder Azure Stream Analytics-Typ hat einen entsprechenden Typ in C#, der in der folgenden Tabelle dargestellt ist:

Dasselbe gilt, wenn Daten von C# zu Azure Stream Analytics übermittelt werden müssen, was beim Ausgabewert einer UDF geschieht. Die folgende Tabelle zeigt die unterstützten Typen:

Die UDF-Funktion hat folgende Einschränkungen:

• Man kann .NET Standard UDFs nur in Visual Studio Code oder Visual Studio erstellen und sie dann in Azure veröffentlichen. Sie können Read-only-Versionen von .NET Standard UDFs unter Functions im Azure-Portal ansehen. Das Azure-Portal unterstützt nicht das Erstellen von .NET-Standard-Funktionen.
• Der Azure-Portal-Abfrageeditor zeigt einen Fehler an, wenn Sie eine .NET Standard UDF im Portal verwenden.
• Du kannst keine externen REST-Endpunkte aufrufen, wie zum Beispiel eine umgekehrte IP-Abfrage oder das Abrufen von Referenzdaten aus einer externen Quelle.
• Da der benutzerdefinierte Code den Kontext mit der Azure Stream Analytics-Engine teilt, kann benutzerdefinierter Code nichts referenzieren, das einen widersprüchlichen Namespace oder DLL-Namen mit Azure Stream Analytics-Code hat. Zum Beispiel kann man Newtonsoft.Json nicht referenzieren.
• Azure Stream Analytics kopiert unterstützende Dateien im Projekt in die User Custom Code Zip-Datei, die es verwendet, wenn Sie den Job in die Cloud veröffentlichen. Während der Dekomprimierung werden alle Dateien in Unterordnern in die Wurzel des User Custom Code-Ordners in der Cloud verschoben. Die Dekompression flacht die Zip-Datei ab.
• Benutzerdefinierter Benutzercode unterstützt keine leeren Ordner. Fügen Sie den Unterstützenden Dateien im Projekt keine leeren Ordner hinzu.

Entwickeln einer UDF in Visual Studio Code

Visual Studio Code-Tools für Azure Stream Analytics erleichtern Ihnen das Schreiben von UDFs, testen Sie Ihre Aufträge lokal (sogar offline), und veröffentlichen Sie Ihren Stream Analytics-Auftrag in Azure. Du kannst .NET Standard UDFs in Visual Studio Code aus einem lokalen Projekt oder aus lokalen DLLs implementieren. Sie können auch auf lokale DLLs verweisen, die die benutzerdefinierten Funktionen enthalten.

Verwenden Sie ein lokales Projekt für komplexe Funktionen, die die volle Leistung einer .NET Standard-Sprache über ihre Ausdruckssprache hinaus erfordern, wie z. B. prozedurale Logik oder Rekursion. Ein lokales Projekt hilft auch, wenn Sie die Funktionslogik über mehrere Azure Stream Analytics-Abfragen teilen müssen, und Sie können Ihre Funktionen lokal debuggen und testen. Im folgenden Beispiel ist CSharpUDFProject ein C#-Klassenbibliotheksprojekt, und ASAUDFDemo das Azure Stream Analytics-Projekt, das auf CSharpUDFProject verweist.

1. Erstelle eine neue .NET Standard-Klassenbibliothek auf deinem lokalen Rechner.

   

2. Schreiben Sie den Code in Ihrer Klasse. Definiere die Klassen als öffentlich und die Objekte als statisch öffentlich. Die folgende UDF multipliziert eine ganze Zahl mit sich selbst, um das Quadrat der ganzen Zahl zu erzeugen.

   using System;
   
   namespace CSharpUDFProject
   {
      //
       public class Class1
       {
           public static Int64 SquareFunction(Int64 a)
           {
               return a * a;
           }
       }
   }
   

3. Füge eine neue C#-Funktions-Konfigurationsdatei in dein Azure Stream Analytics-Projekt hinzu und verweise auf das C#-Klassenbibliotheksprojekt. Um die Funktion hinzuzufügen, wähle und halte den Ordner Functions gedrückt (oder klicke mit der rechten Maustaste auf sie) und wähle dann "Item hinzufügen".

   

4. Fügen Sie Ihrem Azure Stream Analytics-Projekt eine C#-Funktion SquareFunction hinzu.

   

5. Hier kommt der Name der C#-Funktion ins Spiel.

   

6. Wählen Sie in der C#-Funktionskonfiguration Bibliotheksprojektpfad auswählen, um Ihr C#-Projekt aus der Dropdownliste auszuwählen, und wählen Sie Projekt erstellen, um Ihr Projekt zu erstellen. Wählen Sie dann die Select-Klasse und die Select-Methode aus, um den zugehörigen Klassen- und Methodennamen aus der Dropdownliste auszuwählen. Um auf die Methoden, Typen und Funktionen in der Stream Analytics-Abfrage zu verweisen, definieren Sie die Klassen als öffentlich und die Objekte als statisch öffentlich.

   

7. Um stattdessen das C#-UDF aus einer DLL zu verwenden, wählen Sie DLL-Bibliothekspfad auswählen, um den Pfad zur DLL auszuwählen, und wählen Sie dann Klasse auswählen und Methode auswählen.

   

8. Rufen Sie die UDF in Ihrer Azure Stream Analytics-Abfrage auf.

    SELECT price, udf.SquareFunction(price)
    INTO Output
    FROM Input 
   

9. Konfigurieren Sie den Assemblerpfad in der JobConfig.json Job-Konfigurationsdatei im Abschnitt CustomCodeStorage . Dieser Schritt ist für lokale Tests nicht erforderlich.

10. Bevor Sie den Job an Azure senden, konfigurieren Sie den Paketpfad in der JobConfig.json Job-Konfigurationsdatei im Abschnitt CustomCodeStorage. Verwenden Sie Select aus Ihrem Abonnement in CodeLens, um Ihr Abonnement auszuwählen, und wählen Sie den Namen des Speicherkontos und Containers aus der Dropdown-Liste. Lassen Sie "Pfad " als Standard. Dieser Schritt ist für lokale Tests nicht erforderlich.

    

Entwickeln einer UDF in Visual Studio

Man kann UDFs in Visual Studio implementieren, indem man CodeBehind-Dateien in einem ASA-Projekt, ein UDF aus einem lokalen Projekt oder ein bestehendes Paket aus einem Azure-Speicherkonto verwendet. Im folgenden Beispiel ist UDFTest ein C#-Klassenbibliotheksprojekt, und ASAUDFDemo ist das Azure Stream Analytics-Projekt, das sich auf UDFTest bezieht.

Für die CodeBehind-Option schreiben Sie benutzerdefinierte Funktionen in die Datei Script.asql CodeBehind. Visual Studio-Tools kompilieren die CodeBehind-Datei automatisch in eine Assemblerdatei. Die Tools packen die Assemblies als Zip-Datei und laden sie auf Ihr Speicherkonto hoch, wenn Sie Ihren Auftrag bei Azure einreichen. Um zu lernen, wie man ein C# UDF mit CodeBehind schreibt, folge dem C# UDF für Stream Analytics Edge-Jobs-Tutorial .

1. Erstelle eine neue .NET Standard-Klassenbibliothek in deiner Lösung.

   

2. Schreiben Sie den Code in Ihrer Klasse. Definiere die Klassen als öffentlich und die Objekte als statisch öffentlich.

3. Erstellen Sie das Projekt. Die Tools packen alle Artefakte aus dem BIN-Ordner in eine Zip-Datei und laden die Zip-Datei auf das Speicherkonto hoch. Für externe Referenzen verwenden Sie eine Assemblerreferenz anstelle des NuGet-Pakets.

4. Verweisen Sie in Ihrem Azure Stream Analytics-Projekt auf die neue Klasse.

5. Fügen Sie eine neue Funktion in Ihrem Azure Stream Analytics-Projekt hinzu.

6. Konfigurieren Sie den Assemblerpfad in der JobConfig.json Job-Konfigurationsdatei. Setzen Sie den Assemblerpfad auf Local Project Reference oder CodeBehind.

7. Erstellen Sie sowohl das Funktionsprojekt als auch das Azure Stream Analytics-Projekt neu.

8. Baue dein C#-Projekt, damit du eine Referenz zu deinem C#-UDF aus der Azure Stream Analytics-Abfrage hinzufügen kannst.

   

9. Fügen Sie den Verweis auf das C#-Projekt im ASA-Projekt hinzu. Wähle den Referenz-Knoten aus und halte ihn gedrückt (oder klicke mit der rechten Maus) und wähle dann Referenz hinzufügen.

   

10. Wählen Sie den C#-Projektnamen aus der Liste aus.

    

11. Bestätigen Sie, dass UDFTest unter Referenzen im Projektmappen-Explorer erscheint.

    

12. Wähle den Ordner Funktionen , halte sie gedrückt (oder klicke mit der rechten Maustaste auf sie) und wähle dann Neues Element.

    

13. Fügen Sie Ihrem Azure Stream Analytics-Projekt eine C#-Funktion SquareFunction.json hinzu.

    

14. Öffnen Sie die Funktion im Projektmappen-Explorer, um den Konfigurationsdialog anzuzeigen.

    

15. Wählen Sie in der C#-Funktionskonfiguration "Laden aus ASA-Projektreferenz " und den zugehörigen Assembly-, Klassen- und Methodennamen aus der Dropdownliste aus. Um auf die Methoden, Typen und Funktionen in der Stream Analytics-Abfrage zu verweisen, definieren Sie die Klassen als öffentlich und die Objekte als statisch öffentlich.

    

Konfigurieren Sie bestehende .NET-Standard-UDF-Pakete

Sie können .NET Standard UDFs in jeder IDE erstellen und sie aus Ihrer Azure Stream Analytics-Abfrage aufrufen. Nachdem Sie die Assembler-Zip-Pakete in Ihr Azure-Speicherkonto hochgeladen haben, können Sie die Funktionen in Azure Stream Analytics-Abfragen verwenden, indem Sie die Speicherinformationen in der Stream Analytics-Jobkonfiguration einfügen. Mit dieser Option kannst du die Funktion nicht lokal testen, weil die Visual Studio-Tools dein Paket nicht herunterladen. Der Service parst den Paketpfad direkt. Um ein bestehendes Paket zu verwenden:

1. Kompiliere deinen Code und paketiere alle DLLs mithilfe des Pfads /UserCustomCode/CLR/*.

2. Laden Sie es in die Wurzel des Containers in Ihrem Azure-Speicherkonto hoch.UserCustomCode.zip

3. Erweitern Sie in der JobConfig.json Jobkonfigurationsdatei den Abschnitt Konfiguration für benutzerdefinierten Code.

4. Füllen Sie die Konfiguration mit den folgenden vorgeschlagenen Werten aus.

   Setting	Vorgeschlagener Wert
   Ressource für globale Speichereinstellungen	Datenquelle aus aktuellem Konto auswählen
   Abonnement für globale Speichereinstellungen	< Ihr Abonnement >
   Global Storage Settings Storage Account (Speicherkonto für globale Speichereinstellungen)	< Ihr Speicherkonto >
   Ressource für benutzerdefinierte Codespeichereinstellungen	Datenquelle aus aktuellem Konto auswählen
   Custom Code Storage Settings Storage Account (Speicherkonto für Speichereinstellungen für benutzerdefinierten Code)	< Ihr Speicherkonto >
   Custom Code Storage Settings Container (Container für Speichereinstellungen für benutzerdefinierten Code)	< Ihr Speichercontainer >
   Benutzerdefinierte Codeassemblyquelle	Vorhandene Assemblypakete aus der Cloud
   Benutzerdefinierte Codeassemblyquelle	UserCustomCode.zip

Protokolliere benutzerdefinierte Informationen mit der Klasse. StreamingContext.

Durch die Nutzung des Logging-Mechanismus können Sie benutzerdefinierte Informationen während der Ausführung eines Auftrags erfassen. Verwenden Sie Logdaten, um in Echtzeit die Korrektheit des benutzerdefinierten Codes zu debuggen oder zu bewerten. Verwenden Sie die folgenden Schritte, um Log-Nachrichten zu veröffentlichen und auf sie zuzugreifen:

1. Verwenden Sie die Klasse StreamingContext , um diagnostische Informationen mithilfe der Funktion StreamingDiagnostics.WriteError zu veröffentlichen. Der folgende Code zeigt die Schnittstelle, die Azure Stream Analytics bereitstellt.

   public abstract class StreamingContext
   {
       public abstract StreamingDiagnostics Diagnostics { get; }
   }
   
   public abstract class StreamingDiagnostics
   {
       public abstract void WriteError(string briefMessage, string detailedMessage);
   }
   

2. Übergeben Sie StreamingContext als Eingabeparameter an die UDF-Methode und verwenden Sie ihn innerhalb der UDF, um benutzerdefinierte Protokollinformationen zu veröffentlichen. Im folgenden Beispiel MyUdfMethod definiert eine Dateneingabe , die von der Abfrage bereitgestellt wird, und eine Kontexteingabe als die StreamingContext, die von der Laufzeit-Engine bereitgestellt wird.

   public static long MyUdfMethod(long data, StreamingContext context)
   {
       // write log
       context.Diagnostics.WriteError("User Log", "This is a log message");
   
       return data;
   }
   

3. Rufe die UDF in deiner Abfrage auf. Du musst den StreamingContext Wert nicht in der SQL-Abfrage weitergeben, da Azure Stream Analytics automatisch ein Kontextobjekt bereitstellt, wenn ein Eingabeparameter vorhanden ist. Die Verwendung von MyUdfMethod ändert sich nicht, wie in der folgenden Abfrage gezeigt.

   SELECT udf.MyUdfMethod(input.value) as udfValue FROM input
   

4. Zugriff auf Log-Nachrichten über die Diagnoseprotokolle.

Verwandte Inhalte

• Lernprogramm: Schreiben einer benutzerdefinierten C#-Funktion für einen Azure Stream Analytics-Auftrag (Vorschau)
• Lernprogramm: Benutzerdefinierte JavaScript-Funktionen für Azure Stream Analytics
• Erstellen eines Azure Stream Analytics-Auftrags in Visual Studio Code