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

Artikel
02/28/2024

Viktigt!

.Net Standard-användardefinierade funktioner för Azure Stream Analytics dras tillbaka den 30 september 2024. Efter det datumet går det inte att använda funktionen. Övergå till användardefinierade JavaScript-funktioner för Azure Stream Analytics.

Azure Stream Analytics erbjuder ett SQL-liknande frågespråk för att utföra transformeringar 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å valfritt .NET-standardspråk (C#, F#osv.) för att utöka Stream Analytics-frågespråket. Med UDF:er kan du utföra komplexa matematiska beräkningar, importera anpassade ML-modeller med hjälp av ML.NET och använda anpassad imputationslogik 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.

Regioner

Funktionen .NET user-defined-function är aktiverad för molnjobb som körs på Stream Analytics-kluster. Jobb som körs på standard-SKU:n för flera klientorganisationer kan utnyttja den här funktionen i följande offentliga regioner:

Västra centrala USA
Europa, norra
USA, östra
Västra USA
USA, östra 2
Västeuropa

Om du är intresserad av att använda den här funktionen i en annan region kan du begära åtkomst.

Paketsökväg

Formatet för alla UDF-paket har sökvägen /UserCustomCode/CLR/*. DLL:er (Dynamic Link Libraries) och resurser kopieras under /UserCustomCode/CLR/* mappen, vilket hjälper till att isolera användar-DLL:er från system- 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 att Azure Stream Analytics-värden ska användas i C# måste de konverteras från en miljö till en annan. Marshaling sker för alla indataparametrar i en UDF. Varje Azure Stream Analytics-typ har en motsvarande typ i C# som visas i tabellen nedan:

Azure Stream Analytics-typ	C#-typ
bigint	lång
flyttal	dubbel
nvarchar(max)	sträng
datetime	Datum/tid
Post	Ordlistesträng<, objekt>
Matris	Object[]

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

C#-typ	Azure Stream Analytics-typ
lång	bigint
dubbel	flyttal
sträng	nvarchar(max)
Datum/tid	Datetime
Struct	Post
objekt	Post
Object[]	Matris
Ordlistesträng<, objekt>	Post

Utveckla en UDF i Visual Studio Code

Visual Studio Code-verktyg för Azure Stream Analytics gör det enkelt för dig att skriva UDF:er, testa dina jobb lokalt (även offline) och publicera stream analytics-jobbet 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 i ett .NET Standard-språk utöver uttrycksspråket, till exempel procedurlogik eller rekursion. UDF:er från ett lokalt projekt kan också användas när du behöver dela funktionslogik i flera Azure Stream Analytics-frågor. Genom att lägga till UDF:er i ditt lokala projekt kan du felsöka och testa dina funktioner lokalt.

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

Skapa ett nytt .NET-standardklassbibliotek på den lokala datorn.
Skriv koden i din klass. Kom ihåg att klasserna måste definieras som offentliga och att objekt måste definieras som statiska offentliga.
Lägg till en ny CSharp-funktionskonfigurationsfil i ditt Azure Stream Analytics-projekt och referera till CSharp-klassbiblioteksprojektet.
Konfigurera sammansättningssökvägen i jobbkonfigurationsfilen, JobConfig.jsonavsnittet 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-projektet, som refererar till CSharpUDFProject.

Azure Stream Analytics project in Visual Studio Code

Följande UDF har en funktion som multiplicerar ett heltal med sig själv för att skapa heltalets kvadrat. 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 C# UDF-funktionen i Stream Analytics-projektet.

Högerklicka på mappen Functions och välj Lägg till objekt.
Lägg till en C#-funktion SquareFunction i ditt Azure Stream Analytics-projekt.
I C#-funktionskonfigurationen väljer du Välj biblioteksprojektsökväg för att välja ditt C#-projekt i listrutan och väljer 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 Välj sökväg för biblioteksdll för att välja DLL. Välj sedan Välj klass och Välj metod för att välja den relaterade klassen och metodnamnet i listrutan.

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

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

Innan du skickar jobbet till Azure konfigurerar du paketsökvägen i jobbkonfigurationsfilen, JobConfig.jsonavsnittet CustomCodeStorage. Använd Välj från din prenumeration i CodeLens för att välja din prenumeration och välja lagringskontot och containernamnet i listrutan. Lämna Sökvägen 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-verktyg kompilerar automatiskt CodeBehind-filen 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 hjälp av CodeBehind genom att följa självstudien C# UDF for Stream Analytics Edge-jobb .

Lokalt projekt

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

Skapa ett nytt .NET-standardklassbibliotek i din lösning
Skriv koden i din klass. Kom ihåg att klasserna måste definieras som offentliga och att objekt måste definieras som statiska offentliga.
Skapa ditt projekt. Verktygen paketar alla artefakter i mappen bin 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.
Referera till den nya klassen i ditt Azure Stream Analytics-projekt.
Lägg till en ny funktion i ditt Azure Stream Analytics-projekt.
Konfigurera sammansättningssökvägen i jobbkonfigurationsfilen, JobConfig.json. Ange sammansättningssökvägen till Lokal projektreferens eller CodeBehind.
Å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-projektet som refererar till UDFTest.

Azure Stream Analytics IoT Edge project in Visual Studio

Skapa ditt C#-projekt, vilket gör att du kan lägga till en referens till din C# UDF från Azure Stream Analytics-frågan.
Lägg till referensen till C#-projektet i ASA-projektet. Högerklicka på noden Referenser och välj Lägg till referens.
Välj C#-projektnamnet i listan.
Du bör se UDFTest under Referenser i Solution Explorer.
Högerklicka på mappen Functions och välj Nytt objekt.
Lägg till en C#-funktion SquareFunction.json i ditt Azure Stream Analytics-projekt.
Dubbelklicka på funktionen i Solution Explorer för att öppna konfigurationsdialogrutan.
I C#-funktionskonfigurationen väljer du Läs in från ASA-projektreferens 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 roten för containern i ditt Azure Storage-konto.

När zip-paket för sammansättning har laddats upp till ditt Azure-lagringskonto 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-verktyg inte laddar ned 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:

Inställning	Föreslaget värde
Global lagringsresurs Inställningar	Välj datakälla från det aktuella kontot
Global Storage Inställningar-prenumeration	< din prenumeration >
Globalt lagringskonto Inställningar lagring	< ditt lagringskonto >
Anpassad kodlagring Inställningar resurs	Välj datakälla från det aktuella kontot
Lagringskonto för anpassad kod Inställningar	< ditt lagringskonto >
Anpassad kodlagring Inställningar container	< din lagringscontainer >
Sammansättningskälla för anpassad kod	Befintliga sammansättningspaket från molnet
Sammansättningskälla för anpassad kod	UserCustomCode.zip

Användarloggning

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

Med StreamingContext klassen kan du publicera diagnostikinformation med hjälp av StreamingDiagnostics.WriteError funktionen. 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 definierar en datainmatning , som tillhandahålls av frågan, och en kontextinmatning som , StreamingContextsom 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 in av SQL-frågan. Azure Stream Analytics tillhandahåller ett kontextobjekt automatiskt om det finns en indataparameter. Användningen av MyUdfMethod ändras 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 Funktioner i Azure-portalen. Redigering av .NET Standard-funktioner stöds inte i Azure-portalen.
Frågeredigeraren för Azure-portalen visar ett fel när du använder .NET Standard UDF i portalen.
Anropa externa REST-slutpunkter, till exempel att gö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-motorn kan anpassad kod inte referera till något som har ett namnområde i konflikt/dll_name 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 Användaranpassad kod som används när du publicerar jobbet i molnet. Alla filer i undermappar kopieras direkt till roten i mappen Användar anpassad kod i molnet när de packas upp. Dragkedjan är "utplattad" när den är dekomprimerad.
Anpassad användarkod stöder inte tomma mappar. Lägg inte till tomma mappar i stödfilerna i projektet.

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

Regioner

Paketsökväg

Typer och mappning som stöds

Utveckla en UDF i Visual Studio Code

Lokalt projekt

Lokala DLL:er

Exempel

Utveckla en UDF i Visual Studio

Codebehind

Lokalt projekt

Exempel

Befintliga paket

Användarloggning

Begränsningar

Nästa steg

Ytterligare resurser