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

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. Språket innehåller många inbyggda funktioner, men vissa komplexa scenarier kräver mer flexibilitet. Genom att använda .NET Standard användardefinierade funktioner (UDF) kan du anropa egna funktioner skrivna i vilket .NET Standard-språk som helst (till exempel C# eller F#) för att utöka Stream Analytics frågespråket. Använd UDF för att utföra komplexa matematiska beräkningar, importera anpassade ML-modeller med ML.NET och använd anpassad imputationslogik för saknad data.

Eftersom denna funktion är pensionerad, använd denna artikel för att förstå hur .NET Standard UDF fungerade och för att planera din migrering till JavaScript-användardefinierade funktioner.

Om .NET Standard användardefinierade funktioner

.NET Standard UDF:er utökar Stream Analytics-frågespråket med anpassad logik. Innan du bygger en UDF, granska regionerna där funktionen körs, paketvägen den använder, de stödda typmappningarna och funktionsbegränsningarna.

Azure Stream Analytics möjliggör .NET:s användardefinierade funktion för molnjobb som körs på Stream Analytics-kluster. Jobb som körs på Standard multitenant-SKU kan använda denna funktion i följande publika regioner:

• Västra centrala USA
• North Europe
• East US
• West US
• Östra USA 2
• West Europe

För att använda denna funktion i en annan region, begär åtkomst.

Formatet för alla UDF-paket har sökvägen /UserCustomCode/CLR/*. Azure Stream Analytics kopierar dynamiska länkbibliotek (DLL) och resurser under mappen/UserCustomCode/CLR/*, vilket hjälper till att isolera användar-DLL:er från system- och Azure Stream Analytics-DLL:er. Alla funktioner använder denna paketsökväg, oavsett hur du använder dem.

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 följande tabell:

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. Följande tabell visar de stödda typerna:

UDF-funktionen har följande begränsningar:

• Du kan bara skapa .NET Standard UDF:er i Visual Studio Code eller Visual Studio, och sedan publicera dem till Azure. Du kan se skrivskyddade versioner av .NET Standard UDF under Functions i Azure-portalen. Azure-portalen stöder inte att skapa .NET Standard-funktioner.
• Azure-portalens frågeredigerare visar ett fel när du använder en .NET Standard UDF i portalen.
• Du kan inte anropa externa REST-endpoints, till exempel för att göra omvänd IP-uppslagning eller hämta referensdata från en extern källa.
• Eftersom den anpassade koden delar samma kontext med Azure Stream Analytics-motorn kan den inte referera till något som har en namnrymd eller ett DLL-namn som står i konflikt med Azure Stream Analytics-kod. Till exempel kan du inte referera till Newtonsoft.Json.
• Azure Stream Analytics kopierar stödjande filer i projektet till User Custom Code-zipfilen som används när du publicerar jobbet i molnet. Under dekomprimeringen flyttas alla filer i undermappar till roten i User Custom Code-mappen i molnet. Dekomprimering packar upp zipfilen.
• Anpassad användarkod stöder inte tomma mappar. Lägg inte till tomma mappar i stödfilerna i projektet.

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. Du kan implementera .NET Standard UDF:er i Visual Studio Code från ett lokalt projekt eller från lokala DLL:er. Du kan också referera till lokala DLL:er som innehåller de användardefinierade funktionerna.

Använd ett lokalt projekt för komplexa funktioner som kräver hela kraften i ett .NET Standard-språk utöver dess uttrycksspråk, såsom procedurlogik eller rekursion. Ett lokalt projekt hjälper också när du behöver dela funktionslogiken över flera Azure Stream Analytics-frågor, och du kan felsöka och testa dina funktioner lokalt. I följande exempel är CSharpUDFProject ett C#-klassbiblioteksprojekt, och ASAUDFDemo är Azure Stream Analytics-projektet, som refererar till CSharpUDFProject.

1. Skapa ett nytt .NET Standard-klassbibliotek på din lokala maskin.

   

2. Skriv koden i din klass. Definiera klasserna som publika och objekten som statiska publika. Följande UDF multiplicerar ett heltal med sig själv för att producera kvadraten av heltalet.

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

3. Lägg till en ny konfigurationsfil för C#-funktionen i ditt Azure Stream Analytics-projekt och referera till C#-klassbiblioteksprojektet. För att lägga till funktionen, markera och håll (eller högerklicka) på mappen Funktioner , och välj sedan Lägg till objekt.

   

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

   

5. Skriv in C#-funktionens namn.

   

6. I C#-funktionskonfigurationen, välj Välj biblioteksprojekt-väg för att välja ditt C#-projekt från rullgardinsmenyn och välj Bygg projekt för att bygga ditt projekt. 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, definiera klasserna som publika och objekten som statiska publika.

   

7. För att använda C# UDF från en DLL istället, välj Välj biblioteks-dll-väg för att välja DLL, välj sedan Välj klass och Välj metod.

   

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

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

9. Konfigurera assembleringsvägen i jobbkonfigurationsfilen JobConfig.json , i avsnittet CustomCodeStorage . Detta steg behövs inte för lokal testning.

10. Innan du skickar jobbet till Azure, konfigurera paketsökvägen i jobbkonfigurationsfilenJobConfig.json, i avsnittet CustomCodeStorage. Använd Välj från prenumerationerna i CodeLens för att välja din prenumeration och välj lagringskonto och containernamn i listrutan. Lämna Sökvägen som standard. Detta steg behövs inte för lokal testning.

    

Utveckla en UDF i Visual Studio

Du kan implementera UDF:er i Visual Studio genom att använda CodeBehind-filer i ett ASA-projekt, en UDF från ett lokalt projekt eller ett befintligt paket från ett Azure-lagringskonto. I följande exempel är UDFTest ett C#-klassbiblioteksprojekt, och ASAUDFDemo är Azure Stream Analytics-projektet, som refererar till UDFTest.

För CodeBehind-alternativet, skriv användardefinierade funktioner i filen Script.asql CodeBehind. Visual Studio-verktyg kompilerar automatiskt CodeBehind-filen till en assemblerfil. Verktygen paketerar assemblies som en zip-fil och laddar upp dem till ditt lagringskonto när du skickar in ditt jobb till Azure. För att lära dig hur man skriver en C# UDF med CodeBehind, följ C# UDF för Stream Analytics Edge-jobbhandledningen .

1. Skapa ett nytt .NET Standard-klassbibliotek i din lösning.

   

2. Skriv koden i din klass. Definiera klasserna som publika och objekten som statiska publika.

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änd en assembly-referens istä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 ditt Azure Stream Analytics-projekt.

6. Konfigurera assembleringssökvägen i jobbkonfigurationsfilen JobConfig.json . Ställ in assembleringssökvägen till Local Project Reference eller CodeBehind.

7. Återskapa både funktionsprojektet och Azure Stream Analytics-projektet.

8. Bygg ditt C#-projekt så att du kan lägga till en referens till din C# UDF från Azure Stream Analytics-frågan.

   

9. Lägg till referensen till C#-projektet i ASA-projektet. Välj och håll in (eller högerklicka) på Referenser-noden , och välj sedan Lägg till referens.

   

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

    

11. Bekräfta att UDFTest visas under Referenser i Prieskumník riešení.

    

12. Välj och håll in (eller högerklicka) mappen Funktioner , och välj sedan Nytt objekt.

    

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

    

14. Öppna funktionen i Prieskumník riešení för att visa konfigurationsdialogen.

    

15. 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, definiera klasserna som publika och objekten som statiska publika.

    

Konfigurera befintliga .NET Standard UDF-paket

Du kan skapa .NET Standard UDF:er i vilken IDE som helst och anropa dem från din Azure Stream Analytics-fråga. Efter att du laddat upp assembly zip-paketen till ditt Azure-lagringskonto kan du använda funktionerna i Azure Stream Analytics-frågor genom att inkludera lagringsinformationen i Stream Analytics-jobbkonfigurationen. Du kan inte testa funktionen lokalt med detta alternativ eftersom Visual Studio-verktyg inte laddar ner ditt paket. Tjänsten tolkar paketbanan direkt. För att använda ett befintligt paket:

1. Kompiliera din kod och paketera alla DLL:er med hjälp av sökvägen /UserCustomCode/CLR/*.

2. Ladda upp UserCustomCode.zip till roten av containern i ditt Azure-lagringskonto.

3. I JobConfig.json jobbkonfigurationsfilen expanderar du avsnittet Användardefinierad kodkonfiguration.

4. Fyll i konfigurationen med följande föreslagna värden.

   Inställningen	Föreslaget värde
   Resurs för globala lagringsinställningar	Välj datakälla från aktuellt konto
   Prenumeration på globala lagringsinställningar	< din prenumeration >
   Global lagringsinställningar lagringskonto	< ditt lagringskonto >
   Resurs för lagringsinställningar för anpassad kod	Välj datakälla från aktuellt konto
   Lagringskonto för anpassade kodlagringsinställningar	< ditt lagringskonto >
   Container för lagringsinställningar för anpassad kod	< din lagringscontainer >
   Sammansättningskälla för anpassad kod	Befintliga sammansättningspaket från molnet
   Sammansättningskälla för anpassad kod	UserCustomCode.zip

Logga anpassad information med klassen StreamingContext.

Genom att använda loggningsmekanismen kan du fånga anpassad information medan ett jobb körs. Använd loggdata för att felsöka eller bedöma korrektheten i den anpassade koden i realtid. Använd följande steg för att publicera och komma åt loggmeddelanden:

1. Använd klassen StreamingContext för att publicera diagnostisk information med hjälp av funktionen StreamingDiagnostics.WriteError. Följande kod visar gränssnittet som Azure Stream Analytics exponerar.

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

2. Skicka StreamingContext som en indataparameter till UDF-metoden och använd den inom UDF för att publicera anpassad logginformation. I följande exempel definierar MyUdfMethod indata av typen data, som frågan tillhandahåller, och indata av typen context i form av StreamingContext, som körtidsmotorn tillhandahåller.

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

3. Anropa UDF:en i din fråga. Du behöver inte skicka in StreamingContext värdet i SQL-frågan, eftersom Azure Stream Analytics automatiskt tillhandahåller ett kontextobjekt om en indataparameter finns. Användningen av MyUdfMethod ändras inte, vilket visas i följande fråga.

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

4. Åtkomst till loggmeddelanden via diagnostikloggarna.

Relaterat innehåll

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