Door de gebruiker gedefinieerde .NET Standard-functies ontwikkelen Azure Stream Analytics taken (preview)

Azure Stream Analytics biedt een SQL querytaal voor het uitvoeren van transformaties en berekeningen over stromen gebeurtenisgegevens. Er zijn veel ingebouwde functies, maar sommige complexe scenario's vereisen extra flexibiliteit. Met .NET Standard door de gebruiker gedefinieerde functies (UDF) kunt u uw eigen functies aanroepen die zijn geschreven in elke standaardtaal van .NET (C#, F#, enzovoort) om de querytaal van de Stream Analytics uit te breiden. Met UDF's kunt u complexe wiskundige berekeningen uitvoeren, aangepaste ML-modellen importeren met behulp van ML.NET en aangepaste imputatielogica gebruiken voor ontbrekende gegevens. De UDF-functie voor Stream Analytics-taken is momenteel in de previewfase en mag niet worden gebruikt voor productieworkloads.

.NET door de gebruiker gedefinieerde functie voor cloudtaken is beschikbaar in:

• VS - west-centraal
• Europa - noord
• VS - oost
• VS - west
• VS - oost 2
• Europa -west

Als u geïnteresseerd bent in het gebruik van deze functie in een andere regio, kunt u toegang aanvragen. Er is echter geen dergelijke regiobeperking bij het gebruik van Stream Analytics clusters.

Pakketpad

De indeling van een UDF-pakket heeft het pad /UserCustomCode/CLR/* . Dynamic Link Libraries (DLL's) en resources worden gekopieerd in de map , waarmee u gebruikers-DLL's kunt isoleren van systeem- /UserCustomCode/CLR/* en Azure Stream Analytics-DLL's. Dit pakketpad wordt gebruikt voor alle functies, ongeacht de methode die wordt gebruikt om ze te gebruiken.

Ondersteunde typen en toewijzing

Als Azure Stream Analytics in C# wilt gebruiken, moeten ze van de ene omgeving naar de andere worden geseed. De invoerparameters van een UDF worden gebruikt. Elk Azure Stream Analytics type heeft een overeenkomstig type in C# dat wordt weergegeven in de onderstaande tabel:

Hetzelfde geldt wanneer gegevens moeten worden geseed van C# naar Azure Stream Analytics, wat gebeurt op de uitvoerwaarde van een UDF. In de onderstaande tabel ziet u welke typen worden ondersteund:

Een UDF ontwikkelen in Visual Studio Code

Visual Studio Code-hulpprogramma's voor Azure Stream Analytics kunt u eenvoudig UF's schrijven, uw taken lokaal testen (zelfs offline) en uw Stream Analytics publiceren naar Azure.

Er zijn twee manieren om .NET Standard UDF's te implementeren in Visual Studio Code-hulpprogramma's.

• UDF van lokale DLL's
• UDF van een lokaal project

Lokaal project

Door de gebruiker gedefinieerde functies kunnen worden geschreven in een assembly waarnaar later wordt verwezen in een Azure Stream Analytics query. Dit is de aanbevolen optie voor complexe functies waarvoor de volledige kracht van een .NET Standard-taal is vereist naast de expressietaal, zoals procedurele logica of recursie. UDF's van een lokaal project kunnen ook worden gebruikt wanneer u de functielogica wilt delen in verschillende Azure Stream Analytics query's. Door UDF's toe te voegen aan uw lokale project, kunt u lokaal fouten opsporen en uw functies testen.

Verwijzen naar een lokaal project:

1. Maak een nieuwe standaard .NET-klassebibliotheek op uw lokale computer.
2. Schrijf de code in uw klasse. Houd er rekening mee dat de klassen moeten worden gedefinieerd als openbaar en dat objecten moeten worden gedefinieerd als statisch openbaar.
3. Voeg een nieuw CSharp Function-configuratiebestand toe aan uw Azure Stream Analytics en verwijs naar het CSharp-klassebibliotheekproject.
4. Configureer het assemblypad in het taakconfiguratiebestand, JobConfig.json , CustomCodeStorage. Deze stap is niet nodig voor lokaal testen.

Lokale DLL's

U kunt ook verwijzen naar lokale DLL's die de door de gebruiker gedefinieerde functies bevatten.

Voorbeeld

In dit voorbeeld is CSharpUDFProject een C#-klassebibliotheekproject en is ASAUDFDemo het Azure Stream Analytics-project, dat verwijst naar CSharpUDFProject.

De volgende UDF heeft een functie die een geheel getal vermenigvuldigt met zichzelf om het vierkant van het gehele getal te produceren. De klassen moeten worden gedefinieerd als openbaar en objecten moeten worden gedefinieerd als statisch openbaar.

using System;

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

In de volgende stappen ziet u hoe u de functie C# UDF toevoegt aan uw Stream Analytics project.

1. Klik met de rechtermuisknop op de map Functions en kies Item toevoegen.

   

2. Voeg een C#-functie SquareFunction toe aan uw Azure Stream Analytics project.

   

   

3. Selecteer in de C#-functieconfiguratie Bibliotheekprojectpad kiezen om uw C#-project te kiezen in de vervolgkeuzelijst en selecteer Project bouwen om uw project te bouwen. Kies vervolgens Klasse selecteren en Methode selecteren om de gerelateerde klasse en methodenaam te selecteren in de vervolgkeuzelijst. Als u wilt verwijzen naar de methoden, typen en functies in de Stream Analytics-query, moeten de klassen worden gedefinieerd als openbaar en moeten de objecten worden gedefinieerd als statisch openbaar.

   

   Als u de C#-UDF van een DLL wilt gebruiken, selecteert u Bibliotheek-DLL-pad kiezen om de DLL te kiezen. Kies vervolgens Klasse selecteren en Methode selecteren om de gerelateerde klasse en methodenaam te selecteren in de vervolgkeuzelijst.

   

4. Roep de UDF aan in uw Azure Stream Analytics query.

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

5. Voordat u de taak naar Azure indient, configureert u het pakketpad in het taakconfiguratiebestand, JobConfig.json , CustomCodeStorage. Gebruik Selecteren in uw abonnement in CodeLens om uw abonnement te kiezen en kies het opslagaccount en de containernaam in de vervolgkeuzelijst. Laat Pad op de standaardwaarde staan. Deze stap is niet nodig voor lokaal testen.

   

Een UDF ontwikkelen in Visual Studio

Er zijn drie manieren om UF's te implementeren in Visual Studio hulpprogramma's.

• CodeBehind-bestanden in een ASA-project
• UDF van een lokaal project
• Een bestaand pakket van een Azure-opslagaccount

CodeBehind

U kunt door de gebruiker gedefinieerde functies schrijven in script.asql CodeBehind. Visual Studio-hulpprogramma's compileren het CodeBehind-bestand automatisch in een assembly-bestand. De assemblies worden verpakt als zip-bestand en geüpload naar uw opslagaccount wanneer u uw taak naar Azure indient. U kunt leren hoe u een C#-UDF schrijft met behulp van CodeBehind door de zelfstudie C# UDF voor Stream Analytics Edge-taken te volgen.

Lokaal project

Als u wilt verwijzen naar een lokaal project in Visual Studio:

1. Een nieuwe .NET Standard-klassebibliotheek maken in uw oplossing
2. Schrijf de code in uw klasse. Houd er rekening mee dat de klassen moeten worden gedefinieerd als openbaar en dat objecten moeten worden gedefinieerd als statisch openbaar.
3. Compileer het nieuwe project. De hulpprogramma's verpakken alle artefacten in de map bin in een zip-bestand en uploaden het ZIP-bestand naar het opslagaccount. Gebruik voor externe verwijzingen assembly-verwijzing in plaats van het NuGet-pakket.
4. Verwijs naar de nieuwe klasse in uw Azure Stream Analytics project.
5. Voeg een nieuwe functie toe aan uw Azure Stream Analytics project.
6. Configureer het assemblypad in het taakconfiguratiebestand, JobConfig.json . Stel het Assembly-pad in op Local Project Reference of CodeBehind.
7. Bouw zowel het functieproject als het Azure Stream Analytics opnieuw.

Voorbeeld

In dit voorbeeld is UDFTest een C#-klassebibliotheekproject en ASAUDFDemo is het Azure Stream Analytics-project, dat verwijst naar UDFTest.

1. Bouw uw C#-project, waarmee u een verwijzing naar uw C# UDF kunt toevoegen vanuit de Azure Stream Analytics query.

   

2. Voeg de verwijzing toe naar het C#-project in het ASA-project. Klik met de rechtermuisknop op het knooppunt Verwijzingen en kies Verwijzing toevoegen.

   

3. Kies de C#-projectnaam in de lijst.

   

4. U ziet de UDFTest onder Verwijzingen in Solution Explorer.

   

5. Klik met de rechtermuisknop op de map Functions en kies Nieuw item.

   

6. Voeg een C#-SquareFunction.js toe aan uw Azure Stream Analytics project.

   

7. Dubbelklik op de functie in Solution Explorer het configuratiedialoogvenster te openen.

   

8. Kies in de C#-functieconfiguratie Laden vanuit ASA Project Reference en de bijbehorende assembly-, klasse- en methodenamen in de vervolgkeuzelijst. Als u wilt verwijzen naar de methoden, typen en functies in de Stream Analytics-query, moeten de klassen worden gedefinieerd als openbaar en moeten de objecten worden gedefinieerd als statisch openbaar.

   

Bestaande pakketten

U kunt .NET Standard UDF's maken in elke IDE van uw keuze en deze aanroepen vanuit uw Azure Stream Analytics query. Compileer eerst uw code en verpakket alle DLL's. De indeling van het pakket heeft het pad /UserCustomCode/CLR/* . Upload vervolgens naar UserCustomCode.zip de hoofdmap van de container in uw Azure-opslagaccount.

Zodra assembly zip-pakketten zijn geüpload naar uw Azure-opslagaccount, kunt u de functies gebruiken in Azure Stream Analytics query's. U hoeft alleen de opslaggegevens op te nemen in de configuratie van Stream Analytics taak. U kunt de functie niet lokaal testen met deze optie, omdat Visual Studio hulpprogramma's uw pakket niet downloaden. Het pakketpad wordt rechtstreeks naar de service geparseerd.

Als u het assemblypad in het taakconfiguratiebestand wilt configureren, doet u het JobConfig.json volgende:

Vouw de sectie Configuratie van de door de gebruiker gedefinieerde code uit en vul de configuratie in met de volgende voorgestelde waarden:

Gebruikerslogregistratie

Met het mechanisme voor logboekregistratie kunt u aangepaste gegevens vastleggen terwijl een taak wordt uitgevoerd. U kunt logboekgegevens gebruiken om fouten op te sporen of om de juistheid van de aangepaste code in realtime te evalueren.

Met StreamingContext de klasse kunt u diagnostische gegevens publiceren met behulp van de functie StreamingDiagnostics.WriteError . De onderstaande code toont de interface die wordt weergegeven door 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 wordt doorgegeven als invoerparameter voor de UDF-methode en kan worden gebruikt in de UDF om aangepaste logboekgegevens te publiceren. In het onderstaande voorbeeld definieert een gegevensinvoer, die wordt geleverd door de query, en een contextinvoer als de , geleverd MyUdfMethod door de StreamingContext runtime-engine.

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

De StreamingContext waarde hoeft niet te worden doorgegeven door de SQL query. Azure Stream Analytics biedt automatisch een contextobject als er een invoerparameter aanwezig is. Het gebruik van de MyUdfMethod verandert niet, zoals wordt weergegeven in de volgende query:

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

U kunt logboekberichten openen via de Diagnostische logboeken.

Beperkingen

De UDF-preview heeft momenteel de volgende beperkingen:

• .NET Standard UDF's kunnen alleen worden geschreven in Visual Studio Code of Visual Studio en gepubliceerd naar Azure. Alleen-lezen versies van .NET Standard UDF's kunnen worden bekeken onder Functies in de Azure Portal. Het maken van .NET Standard-functies wordt niet ondersteund in de Azure Portal.

• De Azure Portal queryeditor toont een fout bij het gebruik van .NET Standard UDF in de portal.

• Externe REST-eindpunten aanroepen, bijvoorbeeld, het maken van een reverse IP-lookup of het ophalen van referentiegegevens uit een externe bron

• Omdat de aangepaste code context deelt met Azure Stream Analytics-engine, kan aangepaste code niet verwijzen naar iets met een conflicterende naamruimte/dll_name met Azure Stream Analytics code. U kunt bijvoorbeeld niet verwijzen naar Newtonsoft Json.

• Ondersteunende bestanden die in het project zijn opgenomen, worden gekopieerd naar het zip-bestand met aangepaste gebruikerscode dat wordt gebruikt wanneer u de taak naar de cloud publiceert. Alle bestanden in submappen worden rechtstreeks naar de hoofdmap van de map Aangepaste gebruikerscode in de cloud gekopieerd wanneer ze worden uitgepakt. Het zip-bestand wordt 'plat gemaakt' wanneer deze is gedecomprimeerd.

• Aangepaste code van gebruiker biedt geen ondersteuning voor lege mappen. Voeg geen lege mappen toe aan de ondersteunende bestanden in het project.

Volgende stappen

• Zelfstudie: Een door de gebruiker gedefinieerde C#-functie schrijven voor een Azure Stream Analytics taak (preview)
• Zelfstudie: Door gebruiker gedefinieerde JavaScript-functies in Azure Stream Analytics
• Een Azure Stream Analytics maken in Visual Studio Code