Utveckla .NET Standard-användardefinierade funktioner för Azure Stream Analytics jobb (förhandsversion)

Azure Stream Analytics ett SQL frågespråk för att utföra transformationer och beräkningar över strömmar av händelsedata. Det finns många inbyggda funktioner, men vissa komplexa scenarier kräver ytterligare flexibilitet. Med .NET Standard-användardefinierade funktioner (UDF) kan du anropa dina egna funktioner skrivna på val annat .NET-standardspråk (C#, F#, osv.) för att utöka Stream Analytics frågespråket. MedudF:er kan du utföra komplexa matematiska beräkningar, importera anpassade ML-modeller med ML.NET och använda anpassad imputeringslogik för saknade data. UDF-funktionen för Stream Analytics jobb är för närvarande i förhandsversion och bör inte användas i produktionsarbetsbelastningar.

.NET user-defined-function för molnjobb finns i:

• USA, västra centrala
• Europa, norra
• East US
• USA, västra
• USA, östra 2
• Europa, västra

Om du är intresserad av att använda den här funktionen i en annan region kan du begära åtkomst. Det finns dock ingen sådan regionbegränsning när du använder Stream Analytics kluster.

Paketsökväg

Formatet för alla UDF-paket har sökvägen /UserCustomCode/CLR/* . DLL:er (Dynamic Link Libraries) och resurser kopieras under mappen , vilket hjälper dig att isolera /UserCustomCode/CLR/* användar-DLL:er från systemet och Azure Stream Analytics DLL:er. Den här paketsökvägen används för alla funktioner oavsett vilken metod som används för att använda dem.

Typer och mappning som stöds

För Azure Stream Analytics-värden som ska användas i C# måste de vara uppsnalade från en miljö till en annan. Det händer mycket för alla indataparametrar för en UDF. Varje Azure Stream Analytics typ har en motsvarande typ i C# som visas i tabellen nedan:

Samma sak gäller när data måste vara klumpiga från C# till Azure Stream Analytics, vilket sker på utdatavärdet för en UDF. Tabellen nedan visar vilka typer som stöds:

Utveckla en UDF i Visual Studio kod

Visual Studio Code-verktyg för Azure Stream Analytics gör det enkelt för dig att skrivaudf:er, testa dina jobb lokalt (även offline) och publicera ditt Stream Analytics jobb till Azure.

Det finns två sätt att implementera .NET-standard-UDF:er i Visual Studio Code-verktyg.

• UDF från lokala DLL:er
• UDF från ett lokalt projekt

Lokalt projekt

Användardefinierade funktioner kan skrivas i en sammansättning som senare refereras till i en Azure Stream Analytics fråga. Det här är det rekommenderade alternativet för komplexa funktioner som kräver full kraft av ett .NET Standard-språk utöver dess uttrycksspråk, till exempel procedurlogik eller rekursion. Udf:er från ett lokalt projekt kan också användas när du behöver dela funktionslogiken mellan flera Azure Stream Analytics frågor. Genom att lägga till UDF:er i ditt lokala projekt kan du felsöka och testa funktionerna lokalt.

Så här refererar du till ett lokalt projekt:

1. Skapa ett nytt .NET-standardklassbibliotek på den lokala datorn.
2. Skriv koden i klassen. Kom ihåg att klasserna måste definieras som offentliga och att objekt måste definieras som statiska offentliga.
3. Lägg till en ny CSharp Function-konfigurationsfil i ditt Azure Stream Analytics projekt och referera till CSharp-klassbiblioteksprojektet.
4. Konfigurera sammansättningssökvägen i jobbkonfigurationsfilen, JobConfig.json , avsnittet CustomCodeStorage. Det här steget behövs inte för lokal testning.

Lokala DLL:er

Du kan också referera till lokala DLL:er som innehåller de användardefinierade funktionerna.

Exempel

I det här exemplet är CSharpUDFProject ett C#-klassbiblioteksprojekt och ASAUDFDemo är Azure Stream Analytics-projekt som refererar till CSharpUDFProject.

Följande UDF har en funktion som multiplicerar ett heltal med sig själv för att skapa kvadraten av heltal. Klasserna måste definieras som offentliga och objekt måste definieras som statiska offentliga.

using System;

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

Följande steg visar hur du lägger till en C# UDF-funktion i ditt Stream Analytics projekt.

1. Högerklicka på mappen Functions och välj Lägg till objekt.

   

2. Lägg till en C#-funktion SquareFunction i ditt Azure Stream Analytics projekt.

   

   

3. I C#-funktionskonfigurationen väljer du Choose library project path (Välj sökväg för biblioteksprojekt) för att välja C#-projektet i listrutan och väljer Build project (Skapa projekt) för att skapa projektet. Välj sedan Välj klass och Välj metod för att välja den relaterade klassen och metodnamnet i listrutan. För att referera till metoderna, typerna och funktionerna i Stream Analytics-frågan måste klasserna definieras som offentliga och objekten måste definieras som statiska offentliga.

   

   Om du vill använda C# UDF från en DLL väljer du Choose library dll path (Välj sökväg till biblioteks-dll) för att välja DLL-filen. Välj sedan Välj klass och Välj metod för att välja den relaterade klassen och metodnamnet i listrutan.

   

4. Anropa UDF i din Azure Stream Analytics fråga.

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

5. Innan du skickar jobbet till Azure konfigurerar du paketsökvägen i jobbkonfigurationsfilen, JobConfig.json , avsnittet CustomCodeStorage. Använd Välj från din prenumeration i CodeLens för att välja din prenumeration och välj lagringskonto och containernamn i listrutan. Lämna Sökväg som standard. Det här steget behövs inte för lokal testning.

   

Utveckla en UDF i Visual Studio

Det finns tre sätt att implementera UDF:er i Visual Studio verktyg.

• CodeBehind-filer i ett ASA-projekt
• UDF från ett lokalt projekt
• Ett befintligt paket från ett Azure Storage-konto

Codebehind

Du kan skriva användardefinierade funktioner i Script.asql CodeBehind. Visual Studio kompilerar codeBehind-filen automatiskt till en sammansättningsfil. Sammansättningarna paketeras som en ZIP-fil och laddas upp till ditt lagringskonto när du skickar jobbet till Azure. Du kan lära dig hur du skriver en C# UDF med CodeBehind genom att följa självstudien om C# UDF för Stream Analytics Edge-jobb.

Lokalt projekt

Så här refererar du till ett lokalt projekt Visual Studio:

1. Skapa ett nytt .NET-standardklassbibliotek i din lösning
2. Skriv koden i klassen. Kom ihåg att klasserna måste definieras som offentliga och att objekt måste definieras som statiska offentliga.
3. Skapa ditt projekt. Verktygen paketerar alla artefakter i bin-mappen till en zip-fil och laddar upp zip-filen till lagringskontot. För externa referenser använder du sammansättningsreferens i stället för NuGet-paketet.
4. Referera till den nya klassen i ditt Azure Stream Analytics projekt.
5. Lägg till en ny funktion i Azure Stream Analytics projekt.
6. Konfigurera sammansättningssökvägen i jobbkonfigurationsfilen, JobConfig.json . Ange Sammansättningssökväg till Lokal Project eller CodeBehind.
7. Återskapa både funktionsprojektet och Azure Stream Analytics projektet.

Exempel

I det här exemplet är UDFTest ett C#-klassbiblioteksprojekt och ASAUDFDemo är Azure Stream Analytics-projekt, som refererar till UDFTest.

1. Skapa C#-projektet så att du kan lägga till en referens till din C# UDF från Azure Stream Analytics frågan.

   

2. Lägg till referensen till C#-projektet i ASA-projektet. Högerklicka på noden Referenser och välj Lägg till referens.

   

3. Välj C#-projektnamnet i listan.

   

4. Du bör se UDFTest under Referenser i Solution Explorer.

   

5. Högerklicka på mappen Functions och välj Nytt objekt.

   

6. Lägg till en C#-SquareFunction.jsi ditt Azure Stream Analytics projekt.

   

7. Dubbelklicka på funktionen i Solution Explorer för att öppna konfigurationsdialogrutan.

   

8. I C#-funktionskonfigurationen väljer du Läs in från ASA Project-referens och relaterade sammansättnings-, klass- och metodnamn i listrutan. För att referera till metoderna, typerna och funktionerna i Stream Analytics frågan måste klasserna definieras som offentliga och objekten måste definieras som statiska offentliga.

   

Befintliga paket

Du kan skapa .NET Standard-UDF:er i valfri IDE och anropa dem från din Azure Stream Analytics fråga. Kompilera först koden och paketera alla DLL:er. Paketets format har sökvägen /UserCustomCode/CLR/* . Ladda sedan upp UserCustomCode.zip till containerroten i ditt Azure Storage-konto.

När zip-paketen har laddats upp till ditt Azure Storage-konto kan du använda funktionerna i Azure Stream Analytics frågor. Allt du behöver göra är att inkludera lagringsinformationen i Stream Analytics jobbkonfigurationen. Du kan inte testa funktionen lokalt med det här alternativet eftersom Visual Studio inte hämtar paketet. Paketsökvägen parsas direkt till tjänsten.

Så här konfigurerar du sammansättningssökvägen i jobbkonfigurationsfilen: JobConfig.json

Expandera avsnittet användardefinierade kod Configuration avsnittet och fyll i konfigurationen med följande föreslagna värden:

Användarloggning

Med loggningsmekanismen kan du samla in anpassad information när ett jobb körs. Du kan använda loggdata för att felsöka eller utvärdera om den anpassade koden är korrekt i realtid.

Med StreamingContext klassen kan du publicera diagnostikinformation med hjälp av funktionen StreamingDiagnostics.WriteError . Koden nedan visar gränssnittet som exponeras av Azure Stream Analytics.

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

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

StreamingContext skickas som en indataparameter till UDF-metoden och kan användas i UDF för att publicera anpassad logginformation. I exemplet nedan MyUdfMethod definieras en datainmatning, som tillhandahålls av frågan, och en kontextindata som , som StreamingContext tillhandahålls av körningsmotorn.

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

Värdet StreamingContext behöver inte skickas av den SQL frågan. Azure Stream Analytics automatiskt ett kontextobjekt om det finns en indataparameter. Användningen av ändras MyUdfMethod inte, som du ser i följande fråga:

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

Du kan komma åt loggmeddelanden via diagnostikloggarna.

Begränsningar

UDF-förhandsversionen har för närvarande följande begränsningar:

• .NET Standard-UDF:er kan bara redigeras i Visual Studio Code eller Visual Studio och publiceras till Azure. Skrivskyddade versioner av .NET Standard-UDF:er kan visas under Functions i Azure Portal. Redigering av .NET Standard-funktioner stöds inte i Azure Portal.

• Frågeredigeraren Azure Portal visar ett fel när du använder .NET Standard UDF i portalen.

• Anropa externa REST-slutpunkter, till exempel att utföra omvänd IP-sökning eller hämta referensdata från en extern källa

• Eftersom den anpassade koden delar kontext med Azure Stream Analytics motor kan anpassad kod inte referera till något som har en namnrymd/dll_name konflikt med Azure Stream Analytics kod. Du kan till exempel inte referera till Newtonsoft Json.

• Stödfiler som ingår i projektet kopieras till zip-filen user custom code som används när du publicerar jobbet i molnet. Alla filer i undermappar kopieras direkt till roten i mappen Anpassad användarkod i molnet när de packas upp. Zip-filen "plattas ut" när den dekomprimeras.

• Anpassad användarkod stöder inte tomma mappar. Lägg inte till tomma mappar i stödfilerna i projektet.

Nästa steg

• Självstudie: Skriva en C#-användardefinierad funktion för ett Azure Stream Analytics jobb (förhandsversion)
• Självstudier: Användardefinierade funktioner i Azure Stream Analytics JavaScript
• Skapa ett Azure Stream Analytics-jobb i Visual Studio Code