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

L'Analisi di flusso di Azure offre un linguaggio di query simile a SQL per eseguire trasformazioni e calcoli sui flussi di dati degli eventi. Sono disponibili molte funzioni predefinite, ma alcuni scenari complessi richiedono una maggiore flessibilità. Con le funzioni .NET Standard definite dall'utente è possibile richiamare funzioni personalizzate scritte in qualsiasi linguaggio di programmazione .NET Standard (C#, F# e così via) per estendere il linguaggio di query dell'Analisi di flusso di Azure. Le funzioni definite dall'utente consentono di eseguire calcoli matematici complessi, di importare i modelli di Machine Learning personalizzati con ML.NET e di usare la logica di imputazione personalizzata per i dati mancanti. La funzionalità per la creazione di funzioni definite dall'utente per i processi di Analisi di flusso di Azure è attualmente in anteprima e non deve essere usata nei carichi di lavoro di produzione.

Regioni

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

• Stati Uniti centro-occidentali
• Europa settentrionale
• Stati Uniti orientali
• Stati Uniti occidentali
• Stati Uniti orientali 2
• Europa occidentale

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

Percorso del pacchetto

Il formato del pacchetto di una qualsiasi funzione definita dall'utente presenta il percorso /UserCustomCode/CLR/*. Le librerie di collegamento dinamico (DLL) e le risorse vengono copiate nella cartella /UserCustomCode/CLR/*, che consente di isolare le DLL dell'utente dal sistema e dalle DLL di Analisi di flusso di Azure. Questo percorso del pacchetto viene usato per tutte le funzioni, indipendentemente dal metodo usato per queste.

Mapping e tipi supportati

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

Lo stesso vale quando è necessario effettuare il marshalling dei dati da C# ad Analisi di flusso di Azure, che si verifica sul valore di output di una funzione definita dall'utente. La tabella seguente mostra i tipi supportati:

Sviluppare una funzione definita dall'utente in Visual Studio Code

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

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

• Funzione definita dall'utente 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 in seguito fa riferimento una query di Analisi di flusso di Azure. Si tratta dell'opzione consigliata per le funzioni complesse che richiedono la potenza completa di un linguaggio di programmazione .NET Standard oltre al linguaggio delle espressioni, ad esempio una logica procedurale o la ricorsione. Le funzioni definite dall'utente da un progetto locale possono anche essere usate quando è necessario condividere la logica della funzione in diverse query di Analisi di flusso di Azure. L'aggiunta di funzioni definite dall'utente al progetto locale consente di eseguire il debug e il test delle funzioni in locale.

Per fare riferimento a un progetto locale:

1. Creare una nuova libreria di classi .NET Standard nel computer locale.
2. Scrivere il codice nella classe. Tenere presente che le classi devono essere definite come public e gli oggetti devono essere definiti come static public.
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 nel file di configurazione del processo, JobConfig.json, sezione CustomCodeStorage . Questo passaggio non è necessario per i test locali.

DLL locali

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

Esempio

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 funzione definita dall'utente seguente moltiplica un numero intero per se stessa 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;
        }
    }
}

La procedura seguente illustra 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 Scegliere il percorso del 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 Scegli 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. Richiamare la funzione definita dall'utente 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 nel file di configurazione del processo, JobConfig.json, CustomCodeStorage sezione. Usare Seleziona dalla sottoscrizione in CodeLens per scegliere la sottoscrizione e scegliere l'account di archiviazione e il nome del contenitore dall'elenco a discesa. Lasciare Percorso come predefinito. Questo passaggio non è necessario per i test locali.

   

Sviluppare una funzione definita dall'utente in Visual Studio

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

• File CodeBehind in un progetto 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 nel CodeBehind Script.asql. Gli strumenti di Visual Studio compileranno automaticamente il file CodeBehind in un file di assembly. Gli assembly sono inclusi in un pacchetto come file ZIP e caricati nell'account di archiviazione quando si invia il processo ad Azure. È possibile imparare a scrivere una funzione C# definita dall'utente con CodeBehind seguendo l'esercitazione Funzione C# definita dall'utente per i processi di Analisi di flusso di Azure in IoT Edge.

Progetto locale

Per fare riferimento a un progetto locale in Visual Studio:

1. Creare una nuova libreria di classi .NET Standard nella soluzione
2. Scrivere il codice nella classe. Tenere presente che le classi devono essere definite come public e gli oggetti devono essere definiti come static public.
3. Compilare il progetto. Gli strumenti creeranno un pacchetto di tutti gli artefatti presenti nella cartella bin inserendoli in un file con estensione zip che verrà caricato nell'account di archiviazione. Per i riferimenti esterni, usare un riferimento 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 come riferimento al progetto locale o CodeBehind.
7. Ricompilare sia il progetto di funzione sia il progetto di Analisi di flusso di Azure.

Esempio

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 permetterà di aggiungere un riferimento alla funzione C# definita dall'utente dalla query di Analisi di flusso di Azure.

   

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. UDFTest verrà visualizzato nell'elenco 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. Per aprire la finestra di dialogo di configurazione, fare doppio clic sulla funzione in Esplora soluzioni.

   

8. Nella configurazione della funzione C# scegliere Carica dal riferimento al progetto ASA e i nomi di assembly, classe e 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.

   

Pacchetti esistenti

È possibile creare funzioni .NET Standard definite dall'utente in qualsiasi ambiente di sviluppo integrato desiderato e richiamarle dalla query di Analisi di flusso di Azure. Compilare innanzitutto il codice e includere in un pacchetto tutte le DLL. Il formato del pacchetto presenta il percorso /UserCustomCode/CLR/*. Caricare quindi UserCustomCode.zip nella radice del contenitore nell'account di archiviazione di Azure.

Dopo aver caricato i pacchetti ZIP di assembly nel proprio 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. Con questa opzione non è possibile effettuare test in locale per la funzione, in quanto gli strumenti di Visual Studio non scaricheranno il pacchetto. Il percorso del pacchetto viene analizzato direttamente nel servizio.

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

Espandere la sezione Configurazione di codice definito dall'utente e compilare la configurazione con i seguenti valori suggeriti:

Registrazione utente

Il meccanismo di registrazione consente di acquisire informazioni personalizzate mentre un processo è in esecuzione. È 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 viene MyUdfMethod definito 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 dei log tramite i log di diagnostica.

Limitazioni

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

• Le funzioni definite dall'utente .NET Standard possono essere create solo in Visual Studio Code o Visual Studio e pubblicate in Azure. Le versioni di sola lettura delle funzioni .NET Standard definite dall'utente possono essere visualizzate nella sezione Funzioni del portale di Azure. La creazione delle funzioni .NET Standard non è supportata nel portale di Azure.

• L'editor di query del portale di Azure mostra un errore quando nel portale si fa uso della funzione .NET Standard definita dall'utente.

• Chiamate agli endpoint REST esterni, ad esempio per l'esecuzione di una ricerca inversa degli indirizzi IP o per la raccolta di 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ò riferirsi a nessun elemento con uno spazio dei nomi/DLL_name in conflitto con il codice di Analisi di flusso di Azure. Ad esempio, non è possibile fare riferimento al Json di Newtonsoft.

• I file di supporto inclusi nel progetto vengono copiati nel file ZIP user custom code 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 viene decompresso. Il file ZIP viene "appiattito" quando viene decompresso.

• 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 definite dall'utente in Analisi di flusso di Azure
• Creare un processo di Analisi di flusso di Azure in Visual Studio Code