Entwickeln von benutzerdefinierten .NET Standard-Funktionen für Azure Stream Analytics-Aufträge (Vorschau)

Azure Stream Analytics bietet eine SQL-ähnliche Abfragesprache zum Ausführen von Transformationen und Berechnungen über Datenströme von Ereignisdaten. Es gibt viele integrierte Funktionen, aber einige komplexe Szenarien erfordern zusätzliche Flexibilität. Mit benutzerdefinierten .NET Standard-Funktionen (UDF) können Sie ihre eigenen Funktionen aufrufen, die in einer beliebigen .NET-Standardsprache (C#, F# usw.) geschrieben wurden, um die Stream Analytics-Abfragesprache zu erweitern. UDFs ermöglichen es Ihnen, komplexe mathematische Berechnungen durchzuführen, benutzerdefinierte ML-Modelle mithilfe von ML.NET zu importieren und benutzerdefinierte Berechnungslogik für fehlende Daten zu verwenden. Das UDF-Feature für Stream Analytics-Aufträge befindet sich derzeit in der Vorschau und sollte nicht in Produktionsworkloads verwendet werden.

Regions

Das .NET-Feature für benutzerdefinierte Funktionen ist für Cloudaufträge aktiviert, die auf Stream Analytics-Clustern ausgeführt werden. Aufträge, die auf der mehrinstanzenfähigen Standard-SKU ausgeführt werden, können dieses Feature in den folgenden öffentlichen Regionen nutzen:

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

Wenn Sie dieses Feature in einer anderen Region verwenden möchten, können Sie den Zugriff anfordern.

Paketpfad

Das Format eines beliebigen UDF-Pakets weist den Pfad /UserCustomCode/CLR/*auf. Dynamic Link Libraries (DLLs) und Ressourcen werden unter dem /UserCustomCode/CLR/* Ordner kopiert, wodurch Benutzer-DLLs von System- und Azure Stream Analytics-DLLs isoliert werden. Dieser Paketpfad wird unabhängig von der verwendeten Methode für alle Funktionen verwendet.

Unterstützte Typen und Zuordnungen

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 weist einen entsprechenden Typ in C# auf, der in der folgenden Tabelle angezeigt wird:

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

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.

Es gibt zwei Möglichkeiten zum Implementieren von .NET-Standard-UDFs in Visual Studio Code-Tools.

• UDF aus lokalen DLLs
• UDF aus einem lokalen Projekt

Lokales Projekt

Benutzerdefinierte Funktionen können in einer Assembly geschrieben werden, auf die später in einer Azure Stream Analytics-Abfrage verwiesen wird. Dies ist die empfohlene Option für komplexe Funktionen, die die volle Leistungsfähigkeit einer .NET Standardsprache über die Ausdruckssprache hinaus erfordern, z. B. Prozedurlogik oder Rekursion. UDFs aus einem lokalen Projekt können auch verwendet werden, wenn Sie die Funktionslogik für mehrere Azure Stream Analytics-Abfragen freigeben müssen. Durch das Hinzufügen von UDFs zu Ihrem lokalen Projekt können Sie Ihre Funktionen lokal debuggen und testen.

So verweisen Sie auf ein lokales Projekt:

1. Erstellen Sie eine neue .NET-Standardklassenbibliothek auf Ihrem lokalen Computer.
2. Schreiben Sie den Code in Ihrer Klasse. Denken Sie daran, dass die Klassen als öffentlich definiert werden müssen, und objekte müssen als statisch öffentlich definiert werden.
3. Fügen Sie eine neue Konfigurationsdatei für die CSharp-Funktion in Ihrem Azure Stream Analytics-Projekt hinzu, und verweisen Sie auf das CSharp-Klassenbibliotheksprojekt.
4. Konfigurieren Sie den Assemblypfad in der Auftragskonfigurationsdatei, JobConfig.jsonim Abschnitt "CustomCodeStorage ". Dieser Schritt ist für lokale Tests nicht erforderlich.

Lokale DLLs

Sie können auch auf lokale DLLs verweisen, die die benutzerdefinierten Funktionen enthalten.

Example

In diesem Beispiel ist CSharpUDFProject ein C#-Klassenbibliotheksprojekt, und ASAUDFDemo ist das Azure Stream Analytics-Projekt, das auf CSharpUDFProject verweist.

Die folgende UDF verfügt über eine Funktion, die eine ganze Zahl selbst multipliziert, um das Quadrat der ganzen Zahl zu erzeugen. Die Klassen müssen als öffentlich definiert werden, und Objekte müssen als statisch öffentlich definiert werden.

using System;

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

Die folgenden Schritte zeigen, wie Sie Ihrem Stream Analytics-Projekt C#-UDF-Funktion hinzufügen.

1. Klicken Sie mit der rechten Maustaste auf den Ordner "Funktionen ", und wählen Sie "Element hinzufügen" aus.

   

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

   

   

3. Wählen Sie in der C#-Funktionskonfiguration den Pfad des Bibliotheksprojekts aus, um Ihr C#-Projekt aus der Dropdownliste auszuwählen, und wählen Sie "Projekt erstellen" aus, 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, müssen die Klassen als öffentlich definiert werden, und die Objekte müssen als statisch öffentlich definiert werden.

   

   Wenn Sie die C#-UDF aus einer DLL verwenden möchten, wählen Sie "Bibliotheks-DLL-Pfad auswählen", um die DLL auszuwählen. Wählen Sie dann die Select-Klasse und die Select-Methode aus, um den zugehörigen Klassen- und Methodennamen aus der Dropdownliste auszuwählen.

   

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

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

5. Konfigurieren Sie vor dem Übermitteln des Auftrags an Azure den Paketpfad in der Auftragskonfigurationsdatei, im JobConfig.jsonAbschnitt "CustomCodeStorage ". Verwenden Sie "Auswählen" aus Ihrem Abonnement in CodeLens, um Ihr Abonnement auszuwählen und in der Dropdownliste das Speicherkonto und den Containernamen auszuwählen. Lassen Sie "Pfad " als Standard. Dieser Schritt ist für lokale Tests nicht erforderlich.

   

Entwickeln einer UDF in Visual Studio

Es gibt drei Möglichkeiten zum Implementieren von UDFs in Visual Studio-Tools.

• CodeBehind-Dateien in einem ASA-Projekt
• UDF aus einem lokalen Projekt
• Ein vorhandenes Paket aus einem Azure-Speicherkonto

CodeBehind

Sie können benutzerdefinierte Funktionen in script.asql CodeBehind schreiben. Visual Studio-Tools kompilieren die CodeBehind-Datei automatisch in eine Assemblydatei. Die Assemblys werden als ZIP-Datei verpackt und in Ihr Speicherkonto hochgeladen, wenn Sie Ihren Auftrag an Azure übermitteln. Sie erfahren, wie Sie eine C#-UDF mit CodeBehind schreiben, indem Sie dem Lernprogramm für C# UDF für Stream Analytics Edge-Aufträge folgen.

Lokales Projekt

So verweisen Sie in Visual Studio auf ein lokales Projekt:

1. Erstellen einer neuen .NET-Standardklassenbibliothek in Ihrer Lösung
2. Schreiben Sie den Code in Ihrer Klasse. Denken Sie daran, dass die Klassen als öffentlich definiert werden müssen, und objekte müssen als statisch öffentlich definiert werden.
3. Erstellen Sie das Projekt. Die Tools verpacken alle Artefakte im Ordner "bin" in eine ZIP-Datei und laden die ZIP-Datei in das Speicherkonto hoch. Verwenden Sie für externe Verweise den Assemblyverweis 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 Assemblypfad in der Auftragskonfigurationsdatei, JobConfig.json. Legen Sie den Assembly-Pfad auf Local Project Reference oder CodeBehind fest.
7. Erstellen Sie sowohl das Funktionsprojekt als auch das Azure Stream Analytics-Projekt neu.

Example

In diesem Beispiel ist UDFTest ein C#-Klassenbibliotheksprojekt, und ASAUDFDemo ist das Azure Stream Analytics-Projekt, das auf UDFTest verweist.

1. Erstellen Sie Ihr C#-Projekt, mit dem Sie einen Verweis auf Ihre C#-UDF aus der Azure Stream Analytics-Abfrage hinzufügen können.

   

2. Fügen Sie den Verweis auf das C#-Projekt im ASA-Projekt hinzu. Klicken Sie mit der rechten Maustaste auf den Knoten "Verweise", und wählen Sie "Verweis hinzufügen" aus.

   

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

   

4. UDFTest sollte unter Verweise im Projektmappen-Explorer aufgeführt werden.

   

5. Klicken Sie mit der rechten Maustaste auf den Ordner "Funktionen ", und wählen Sie "Neues Element" aus.

   

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

   

7. Doppelklicken Sie im Projektmappen-Explorer auf die Funktion, um das Konfigurationsdialogfeld zu öffnen.

   

8. 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, müssen die Klassen als öffentlich definiert werden, und die Objekte müssen als statisch öffentlich definiert werden.

   

Vorhandene Pakete

Sie können .NET Standard-UDFs in einer beliebigen IDE Ihrer Wahl erstellen und aus Ihrer Azure Stream Analytics-Abfrage aufrufen. Kompilieren Sie zuerst Ihren Code, und verpacken Sie alle DLLs. Das Format des Pakets weist den Pfad /UserCustomCode/CLR/*auf. Laden Sie UserCustomCode.zip dann in das Stammverzeichnis des Containers in Ihrem Azure-Speicherkonto hoch.

Nachdem Assembly-ZIP-Pakete in Ihr Azure-Speicherkonto hochgeladen wurden, können Sie die Funktionen in Azure Stream Analytics-Abfragen verwenden. Sie müssen lediglich die Speicherinformationen in die Stream Analytics-Auftragskonfiguration einschließen. Sie können die Funktion nicht lokal mit dieser Option testen, da Visual Studio-Tools Ihr Paket nicht herunterladen. Der Paketpfad wird direkt an den Dienst übergeben.

So konfigurieren Sie den Assemblypfad in der Auftragskonfigurationsdatei: JobConfig.json

Erweitern Sie die Sektion benutzerdefinierte Code-Konfiguration und füllen Sie die Konfiguration mit den folgenden vorgeschlagenen Werten aus:

Benutzerprotokollierung

Mit dem Protokollierungsmechanismus können Sie benutzerdefinierte Informationen erfassen, während ein Auftrag ausgeführt wird. Sie können Protokolldaten verwenden, um die Richtigkeit des benutzerdefinierten Codes in Echtzeit zu debuggen oder zu bewerten.

Mit StreamingContext der Klasse können Sie Diagnoseinformationen mithilfe der StreamingDiagnostics.WriteError Funktion veröffentlichen. Der folgende Code zeigt die Schnittstelle, die von Azure Stream Analytics verfügbar gemacht wird.

public abstract class StreamingContext
{
    public abstract StreamingDiagnostics Diagnostics { get; }
}

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

StreamingContext wird als Eingabeparameter an die UDF-Methode übergeben und kann innerhalb der UDF verwendet werden, um benutzerdefinierte Protokollinformationen zu veröffentlichen. Im folgenden Beispiel definiert MyUdfMethod eine Dateneingabe (data), die von der Abfrage bereitgestellt wird, und eine Kontexteingabe (context) als StreamingContext, die von der Runtime-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;
}

Der StreamingContext Wert muss nicht von der SQL-Abfrage übergeben werden. Azure Stream Analytics stellt automatisch ein Kontextobjekt bereit, wenn ein Eingabeparameter vorhanden ist. Die Verwendung der MyUdfMethod Funktion ändert sich nicht, wie in der folgenden Abfrage dargestellt:

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

Sie können über die Diagnoseprotokolle auf Protokollnachrichten zugreifen.

Einschränkungen

Die UDF-Vorschau weist derzeit die folgenden Einschränkungen auf:

• .NET Standard UDFs können nur in Visual Studio Code oder Visual Studio erstellt und in Azure veröffentlicht werden. Schreibgeschützte Versionen von .NET Standard UDFs können unter Funktionen im Azure-Portal angezeigt werden. Die Erstellung von .NET Standard-Funktionen wird im Azure-Portal nicht unterstützt.

• Der Abfrage-Editor des Azure-Portals zeigt einen Fehler bei verwendung von .NET Standard UDF im Portal an.

• Aufrufen externer REST-Endpunkte, z. B. durch Reverse-IP-Nachschlagevorgang oder Abrufen von Referenzdaten aus einer externen Quelle

• Da der Kontext des benutzerdefinierten Codes mit der Azure Stream Analytics-Engine geteilt wird, kann der benutzerdefinierte Code nichts referenzieren, das einen widersprüchlichen Namespace oder dll_name mit dem Azure Stream Analytics-Code aufweist. Sie können z. B. nicht auf Newtonsoft Json verweisen.

• Unterstützende Dateien, die im Projekt enthalten sind, werden in die Zip-Datei mit benutzerdefiniertem Code kopiert, die verwendet wird, wenn Sie den Auftrag in der Cloud veröffentlichen. Alle Dateien in Unterordnern werden beim Entpacken direkt in den Stammordner des Ordners "Benutzerdefinierter Code" in der Cloud kopiert. Die Zip-Datei wird beim Dekomprimieren "vereinfacht".

• Benutzerdefinierter Benutzercode unterstützt keine leeren Ordner. Fügen Sie den Unterstützenden Dateien im Projekt keine leeren Ordner hinzu.

Nächste Schritte

• 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