Sviluppare funzioni definite dall'utente .NET Standard per i processi di Analisi di flusso di Azure (anteprima)

Analisi di flusso di Azure offre un linguaggio di query simile a SQL per l'esecuzione di trasformazioni e calcoli su flussi di dati degli eventi. Esistono molte funzioni predefinite, ma alcuni scenari complessi richiedono una maggiore flessibilità. Con le funzioni definite dall'utente (UDF) .NET Standard, è possibile richiamare funzioni personalizzate scritte in qualsiasi linguaggio standard .NET (C#, F#e così via) per estendere il linguaggio di query di Analisi di flusso. Le funzioni definite dall'utente consentono di eseguire calcoli matematici complessi, importare modelli di Machine Learning personalizzati usando ML.NET e applicare logiche di imputazione personalizzate per i dati mancanti. La funzionalità UDF per i Stream Analytics è attualmente in anteprima e non deve essere usata nei carichi di lavoro di produzione.

Regioni

La funzionalità .NET di funzioni definite dall'utente è abilitata per i processi cloud eseguiti nei cluster di Stream Analytics. I processi eseguiti nello SKU multi-tenant Standard possono sfruttare questa funzionalità nelle aree pubbliche seguenti:

• Stati Uniti centro-occidentali
• North Europe
• Stati Uniti orientali
• Stati Uniti occidentali
• Stati Uniti orientali 2
• West Europe

Se si è interessati a usare questa funzionalità in un'altra area, è possibile richiedere l'accesso.

Percorso pacchetto

Il formato di qualsiasi pacchetto UDF ha il percorso /UserCustomCode/CLR/*. Le librerie a collegamento dinamico (DLL) e le risorse vengono copiate nella /UserCustomCode/CLR/* cartella , che consente di isolare le DLL utente dalle DLL di sistema e di Analisi di flusso di Azure. Questo percorso del pacchetto viene usato per tutte le funzioni indipendentemente dal metodo usato per usarli.

Tipi e mapping supportati

Per usare i valori di Analisi di flusso di Azure in C#, è necessario effettuare il marshalling da un ambiente all'altro. Il marshalling avviene per tutti i parametri di input di una funzione definita dall'utente (UDF). Ogni tipo di Analisi di flusso di Azure ha un tipo corrispondente in C# illustrato nella tabella seguente:

Lo stesso vale quando è necessario eseguire il marshalling dei dati da C# ad Azure Stream Analytics, operazione che avviene sul valore di output di una UDF. La tabella seguente illustra i tipi supportati:

Sviluppare una funzione definita dall'utente in Visual Studio Code

Gli strumenti di Visual Studio Code per Azure Stream Analytics semplificano la scrittura di UDF (funzioni definite dall'utente), il test dei processi in locale (anche offline) e la pubblicazione del processo di Stream Analytics in Azure.

Esistono due modi per implementare funzioni definite dall'utente standard .NET negli strumenti di Visual Studio Code.

• Funzione definita dall'utente proveniente da DLL locali
• Funzione definita dall'utente da un progetto locale

Progetto locale

Le funzioni definite dall'utente possono essere scritte in un assembly a cui viene fatto riferimento in un secondo momento in una query di Analisi di flusso di Azure. Questa è l'opzione consigliata per funzioni complesse che richiedono la potenza completa di un linguaggio .NET Standard oltre il linguaggio delle espressioni, ad esempio la logica procedurale o la ricorsione. Le funzioni definite dall'utente da un progetto locale possono essere usate anche quando è necessario condividere la logica della funzione tra diverse query di Analisi di flusso di Azure. Aggiungendo funzioni definite dall'utente al progetto locale, hai la possibilità di eseguire il debug e testare le tue funzioni localmente.

Per fare riferimento a un progetto locale:

1. Creare una nuova libreria di classi standard .NET nel computer locale.
2. Scrivi il codice nella tua classe. Tenere presente che le classi devono essere definite come pubbliche e gli oggetti devono essere definiti come pubblici statici.
3. Aggiungere un nuovo file di configurazione della funzione CSharp nel progetto di Analisi di flusso di Azure e fare riferimento al progetto di libreria di classi CSharp.
4. Configurare il percorso dell'assembly nella sezione JobConfig.json nel file di configurazione del processo. Questo passaggio non è necessario per i test locali.

DLL locali

È anche possibile fare riferimento a DLL locali che includono le funzioni definite dall'utente.

Example

In questo esempio CSharpUDFProject è un progetto di libreria di classi C# e ASAUDFDemo è il progetto di Analisi di flusso di Azure, che farà riferimento a CSharpUDFProject.

La seguente Funzione Definita dall'Utente (UDF) ha una funzione che moltiplica un numero intero per se stesso per produrre il quadrato dell'intero. Le classi devono essere definite come pubbliche e gli oggetti devono essere definiti come pubblici statici.

using System;

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

I passaggi seguenti illustrano come aggiungere la funzione UDF C# al progetto di Analisi di flusso.

1. Fare clic con il pulsante destro del mouse sulla cartella Funzioni e scegliere Aggiungi elemento.

   

2. Aggiungere una funzione C# SquareFunction al progetto di Analisi di flusso di Azure.

   

   

3. Nella configurazione della funzione C# selezionare Scegli percorso progetto libreria per scegliere il progetto C# dall'elenco a discesa e selezionare Compila progetto per compilare il progetto. Scegliere quindi Seleziona classe e Seleziona metodo per selezionare la classe e il nome del metodo correlati dall'elenco a discesa. Per fare riferimento ai metodi, ai tipi e alle funzioni nella query di Analisi di flusso, le classi devono essere definite come pubbliche e gli oggetti devono essere definiti come pubblici statici.

   

   Se si vuole usare la funzione definita dall'utente C# da una DLL, selezionare Scegliere il percorso dll della libreria per scegliere la DLL. Scegliere quindi Seleziona classe e Seleziona metodo per selezionare la classe e il nome del metodo correlati dall'elenco a discesa.

   

4. Richiama la UDF nella query di Analisi di flusso di Azure.

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

5. Prima di inviare il processo ad Azure, configurare il percorso del pacchetto nella sezione JobConfig.json nel file di configurazione del processo. Usare Seleziona dalla sottoscrizione in CodeLens per scegliere la sottoscrizione; scegliere quindi l'account di archiviazione e il nome del contenitore dall'elenco a discesa. Lasciare Il percorso predefinito. Questo passaggio non è necessario per i test locali.

   

Sviluppare una funzione definita dall'utente in Visual Studio

Esistono tre modi per implementare UDFs (funzioni definite dall'utente) negli strumenti di Visual Studio.

• File CodeBehind nei progetti ASA
• Funzione definita dall'utente da un progetto locale
• Un pacchetto esistente da un account di archiviazione di Azure

CodeBehind

È possibile scrivere funzioni definite dall'utente in Script.asql CodeBehind. Gli strumenti di Visual Studio compileranno automaticamente il file CodeBehind in un file di assembly. Gli assembly vengono confezionati in un archivio ZIP e caricati nel tuo account di archiviazione quando invii il tuo processo ad Azure. Per informazioni su come scrivere una funzione definita dall'utente (UDF) C# usando CodeBehind, seguire l'esercitazione sulla UDF C# per i processi di Analisi di flusso Edge.

Progetto locale

Per fare riferimento a un progetto locale in Visual Studio:

1. Creare una nuova libreria di classi standard .NET nella soluzione
2. Scrivi il codice nella tua classe. Tenere presente che le classi devono essere definite come pubbliche e gli oggetti devono essere definiti come pubblici statici.
3. Crea il progetto. Gli strumenti comprimeranno tutti gli artefatti nella cartella bin in un file ZIP e caricheranno il file ZIP nell'account di archiviazione. Per i riferimenti esterni, usare il riferimento all'assembly anziché il pacchetto NuGet.
4. Fare riferimento alla nuova classe nel progetto di Analisi di flusso di Azure.
5. Aggiungere una nuova funzione nel progetto di Analisi di flusso di Azure.
6. Configurare il percorso dell'assembly nel file di configurazione del processo, JobConfig.json. Impostare il percorso dell'assembly su Riferimento progetto locale o CodeBehind.
7. Ricompilare sia il progetto di funzione che il progetto di Analisi di flusso di Azure.

Example

In questo esempio UDFTest è un progetto di libreria di classi C# e ASAUDFDemo è il progetto di Analisi di flusso di Azure, che farà riferimento a UDFTest.

1. Compilare il progetto C#, che consentirà di aggiungere un riferimento alla UDF C# dalla query di Azure Stream Analytics.

   

2. Aggiungere il riferimento al progetto C# nel progetto ASA. Fare clic con il pulsante destro del mouse sul nodo Riferimenti e scegliere Aggiungi riferimento.

   

3. Scegliere il nome del progetto C# dall'elenco.

   

4. Dovresti vedere UDFTest elencato sotto Riferimenti in Esplora Soluzioni.

   

5. Fare clic con il pulsante destro del mouse sulla cartella Funzioni e scegliere Nuovo elemento.

   

6. Aggiungere una funzione C# SquareFunction.json al progetto di Analisi di flusso di Azure.

   

7. Fare doppio clic sulla funzione in Esplora soluzioni per aprire la finestra di dialogo di configurazione.

   

8. Nella configurazione della funzione C# scegliere Carica da Riferimento progetto ASA e i nomi di assembly, classi e metodi correlati dall'elenco a discesa. Per fare riferimento ai metodi, ai tipi e alle funzioni nella query di Analisi di flusso, le classi devono essere definite come pubbliche e gli oggetti devono essere definiti come pubblici statici.

   

Pacchetti esistenti

È possibile creare funzioni definite dall'utente .NET Standard in qualsiasi IDE preferito e richiamarle dalla query di Analisi di flusso di Azure. Compilare prima di tutto il codice e creare il pacchetto di tutte le DLL. Il formato del pacchetto ha il percorso /UserCustomCode/CLR/*. Quindi, caricate UserCustomCode.zip alla radice del contenitore nel vostro account di archiviazione di Azure.

Dopo aver caricato i pacchetti ZIP dell'assembly nell'account di archiviazione di Azure, è possibile usare le funzioni nelle query di Analisi di flusso di Azure. È sufficiente includere le informazioni di archiviazione nella configurazione del processo di Analisi di flusso. Non è possibile testare la funzione in locale con questa opzione perché gli strumenti di Visual Studio non scaricherà il pacchetto. Il percorso del pacchetto viene analizzato direttamente al servizio.

Per configurare il percorso dell'assembly nel file di configurazione del processo, JobConfig.json:

Espandi la sezione User-Defined Code Configuration e compila la configurazione con i seguenti valori suggeriti:

Registrazione utente

Il meccanismo di registrazione consente di acquisire informazioni personalizzate durante l'esecuzione di un processo. È possibile usare i dati di log per eseguire il debug o valutare la correttezza del codice personalizzato in tempo reale.

La StreamingContext classe consente di pubblicare informazioni di diagnostica usando la StreamingDiagnostics.WriteError funzione . Il codice seguente mostra l'interfaccia esposta da Analisi di flusso di Azure.

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

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

StreamingContext viene passato come parametro di input al metodo UDF e può essere usato all'interno della funzione definita dall'utente per pubblicare informazioni di log personalizzate. Nell'esempio seguente, MyUdfMethod definisce un input di dati, fornito dalla query, e un input di contesto come StreamingContext, fornito dal motore di runtime.

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

Il StreamingContext valore non deve essere passato dalla query SQL. Analisi di flusso di Azure fornisce automaticamente un oggetto di contesto se è presente un parametro di input. L'uso di MyUdfMethod non cambia, come illustrato nella query seguente:

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

È possibile accedere ai messaggi di log tramite i log di diagnostica.

Limitazioni

L'anteprima della funzione definita dall'utente presenta attualmente le limitazioni seguenti:

• Le funzioni definite dall'utente (UDF) .NET Standard possono essere create solo in Visual Studio Code o Visual Studio e pubblicate su Azure. Le versioni di sola lettura delle funzioni definite dall'utente .NET Standard sono visibili in Funzioni nel portale di Azure. La creazione di funzioni .NET Standard non è supportata nel portale di Azure.

• L'editor di query del portale di Azure visualizza un errore quando si usa una UDF definita dall'utente .NET Standard nel portale.

• Chiamare endpoint REST esterni, ad esempio eseguendo una ricerca IP inversa o eseguendo il pull dei dati di riferimento da un'origine esterna

• Poiché il codice personalizzato condivide il contesto con il motore di Analisi di flusso di Azure, il codice personalizzato non può fare riferimento a nulla con uno spazio dei nomi/dll_name in conflitto con il codice di Analisi di flusso di Azure. Ad esempio, non è possibile fare riferimento a Newtonsoft Json.

• I file di supporto inclusi nel progetto vengono copiati nel file ZIP del codice personalizzato utente usato quando si pubblica il processo nel cloud. Tutti i file nelle sottocartelle vengono copiati direttamente nella radice della cartella User Custom Code nel cloud quando l'archivio viene decompresso. La zip è "appiattita" quando viene decompressa.

• Il codice personalizzato dell'utente non supporta cartelle vuote. Non aggiungere cartelle vuote ai file di supporto nel progetto.

Passaggi successivi

• Esercitazione: Scrivere una funzione C# definita dall'utente per un processo di Analisi di flusso di Azure (anteprima)
• Esercitazione: Funzioni javaScript di Analisi di flusso di Azure definite dall'utente
• Creare un processo di Analisi di flusso di Azure in Visual Studio Code