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

Belangrijk

Door de gebruiker gedefinieerde .Net Standard-functies voor Azure Stream Analytics worden op 30 september 2024 buiten gebruik gesteld. Na die datum is het niet mogelijk om de functie te gebruiken. Overgang naar door de gebruiker gedefinieerde JavaScript-functies voor Azure Stream Analytics.

Azure Stream Analytics biedt een SQL-achtige querytaal voor het uitvoeren van transformaties en berekeningen over stromen van gebeurtenisgegevens. Er zijn veel ingebouwde functies, maar voor sommige complexe scenario's is extra flexibiliteit vereist. Met door de gebruiker gedefinieerde .NET Standard-functies (UDF) kunt u uw eigen functies aanroepen die zijn geschreven in elke standaardtaal van .NET (C#, F#, enzovoort) om de Stream Analytics-querytaal uit te breiden. Met UDF's kunt u complexe wiskundige berekeningen uitvoeren, aangepaste ML-modellen importeren met 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.

Regio's

De functie .NET door de gebruiker gedefinieerde functie is ingeschakeld voor cloudtaken die worden uitgevoerd op Stream Analytics-clusters. Taken die worden uitgevoerd op de Standard-SKU met meerdere tenants, kunnen gebruikmaken van deze functie in de volgende openbare regio's:

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

Als u deze functie in een andere regio wilt gebruiken, kunt u toegang aanvragen.

Pakketpad

De indeling van een UDF-pakket heeft het pad /UserCustomCode/CLR/*. Dynamic Link Libraries (DLL's) en resources worden gekopieerd onder de /UserCustomCode/CLR/* map, waarmee u gebruikers-DLL's kunt isoleren van systeem- 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 toewijzingen

Om Azure Stream Analytics-waarden te kunnen gebruiken in C#, moeten ze worden marshaled van de ene omgeving naar de andere. Marshaling vindt plaats voor alle invoerparameters van een UDF. Elk Azure Stream Analytics-type heeft een bijbehorend type in C# dat wordt weergegeven in de onderstaande tabel:

Azure Stream Analytics-type	C#-type
bigint	long
zwevend	dubbel
nvarchar(max)	tekenreeks
datetime	DateTime
Opnemen	Woordenlijsttekenreeks<, object>
Matrix	Object[]

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

C#-type	Azure Stream Analytics-type
long	bigint
dubbel	zwevend
tekenreeks	nvarchar(max)
DateTime	dateTime
Struct	Opnemen
object	Opnemen
Object[]	Matrix
Woordenlijsttekenreeks<, object>	Opnemen

Een UDF ontwikkelen in Visual Studio Code

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

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

• UDF uit 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 buiten de expressietaal is vereist, zoals procedurele logica of recursie. UDF's van een lokaal project kunnen ook worden gebruikt wanneer u de functielogica moet 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.

Ga als volgende te werk om te verwijzen naar een lokaal project:

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

Lokale DLL's

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

Opmerking

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 kwadraat 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 C# UDF-functie 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 configuratie van de C#-functie het pad bibliotheekproject 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 uit een DLL wilt gebruiken, selecteert u Dll-pad van de bibliotheek kiezen om het DLL-bestand 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 verzendt, configureert u het pakketpad in het taakconfiguratiebestand, JobConfig.jsonde sectie CustomCodeStorage. Gebruik Select in uw abonnement in CodeLens om uw abonnement te kiezen en kies het opslagaccount en de containernaam in de vervolgkeuzelijst. Laat pad standaard staan. Deze stap is niet nodig voor lokaal testen.

   

Een UDF ontwikkelen in Visual Studio

Er zijn drie manieren om UDF'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 assemblybestand. De assembly's worden verpakt als een zip-bestand en geüpload naar uw opslagaccount wanneer u uw taak naar Azure verzendt. 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

Ga als volgende te werk om te verwijzen naar een lokaal project in Visual Studio:

1. Een nieuwe .NET Standard-klassebibliotheek maken in uw oplossing
2. Schrijf de code in uw klas. Houd er rekening mee dat de klassen moeten worden gedefinieerd als openbaar en dat objecten als statisch openbaar moeten worden gedefinieerd.
3. Bouw uw project. De hulpprogramma's verpakken alle artefacten in de map Bin naar een zip-bestand en uploaden het zip-bestand naar het opslagaccount. Gebruik voor externe verwijzingen assemblyverwijzingen 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 assemblypad in op Lokaal projectreferentie of CodeBehind.
7. Bouw zowel het functieproject als het Azure Stream Analytics-project opnieuw.

Opmerking

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 naar het C#-project toe 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. De UDFTest wordt weergegeven onder Verwijzingen in Solution Explorer.

   

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

   

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

   

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

   

8. Kies in de configuratie van de C#-functie Laden uit ASA-projectverwijzing en de gerelateerde 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 pak alle DLL's in. De indeling van het pakket heeft het pad /UserCustomCode/CLR/*. Upload vervolgens UserCustomCode.zip naar de hoofdmap van de container in uw Azure-opslagaccount.

Zodra zip-pakketten voor assembly's zijn geüpload naar uw Azure-opslagaccount, kunt u de functies in Azure Stream Analytics-query's gebruiken. U hoeft alleen de opslaggegevens op te nemen in de configuratie van de 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, gaat JobConfig.jsonu als volgende te werk:

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

Instelling	Voorgestelde waarde
Resource globale opslaginstellingen	Kies gegevensbron van het huidige account
Abonnement voor globale opslaginstellingen	< uw abonnement >
Globale opslaginstellingen opslagaccount	< uw opslagaccount >
Resource aangepaste code opslaginstellingen	Kies gegevensbron van het huidige account
Aangepaste code opslaginstellingen opslagaccount	< uw opslagaccount >
Container aangepaste code opslaginstellingen	< uw opslagcontainer >
Aangepaste codeassemblybron	Bestaande assemblypakketten uit de cloud
Aangepaste codeassemblybron	UserCustomCode.zip

Gebruikerslogboekregistratie

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.

StreamingContext Met de klasse kunt u diagnostische gegevens publiceren met behulp van de StreamingDiagnostics.WriteError functie. In de onderstaande code ziet u 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 aan de UDF-methode en kan worden gebruikt in de UDF om aangepaste logboekgegevens te publiceren. In het onderstaande MyUdfMethod voorbeeld definieert u een gegevensinvoer , die wordt geleverd door de query en een contextinvoer als de StreamingContext, die wordt geleverd door de 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 door de SQL-query te worden doorgegeven. Azure Stream Analytics biedt automatisch een contextobject als er een invoerparameter aanwezig is. Het gebruik van de MyUdfMethod bewerking wordt niet gewijzigd, 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 gemaakt in Visual Studio Code of Visual Studio en worden gepubliceerd naar Azure. Alleen-lezen versies van .NET Standard UDF's kunnen worden weergegeven onder Functies in Azure Portal. Ontwerpen van .NET Standard-functies wordt niet ondersteund in Azure Portal.

• In de Query-editor van Azure Portal wordt een fout weergegeven 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 de Azure Stream Analytics-engine, kan aangepaste code niet verwijzen naar iets dat een conflicterende naamruimte/dll_name met Azure Stream Analytics-code heeft. U kunt bijvoorbeeld niet verwijzen naar Newtonsoft Json.

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

• Aangepaste gebruikerscode 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 de gebruiker gedefinieerde Azure Stream Analytics JavaScript-functies
• Een Azure Stream Analytics-taak maken in Visual Studio Code