Eseguire e testare U-SQL con Azure Data Lake U-SQL SDK

Importante

Azure Data Lake Analytics è stato ritirato il 29 febbraio 2024. Per altre informazioni, vedere questo annuncio.

Per l'analisi dei dati, l'organizzazione può usare Azure Synapse Analytics o Microsoft Fabric.

Quando si sviluppa uno script U-SQL, è comune eseguire e testare lo script U-SQL in locale prima di inviarlo al cloud. Azure Data Lake offre un pacchetto NuGet denominato Azure Data Lake U-SQL SDK per questo scenario, tramite il quale è possibile ridimensionare facilmente l'esecuzione e il test di U-SQL. È anche possibile integrare questo test U-SQL con il sistema CI (Continuous Integration) per automatizzare la compilazione e il test.

Se ci si preoccupa di come eseguire manualmente lo script U-SQL ed eseguirne il debug con gli strumenti dell'interfaccia utente grafica, è possibile usare Strumenti Azure Data Lake per Visual Studio. Puoi saperne di più da qui.

Installare Azure Data Lake U-SQL SDK

È possibile ottenere l'SDK U-SQL di Azure Data Lake qui in Nuget.org. Prima di usarlo, è necessario assicurarsi di avere dipendenze come indicato di seguito.

Dipendenze

Data Lake U-SQL SDK richiede le dipendenze seguenti:

Microsoft .NET Framework 4.6 o versione successiva.
Microsoft Visual C++ 14 e Windows SDK 10.0.10240.0 o versione successiva (denominato CppSDK in questo articolo). Esistono due modi per ottenere CppSDK:
- Installare Visual Studio Community Edition. Si avrà una cartella \Windows Kits\10 nella cartella Programmi, ad esempio C:\Programmi (x86)\Windows Kits\10. Troverai anche la versione di Windows 10 SDK in \Windows Kits\10\Lib. Se queste cartelle non vengono visualizzate, reinstallare Visual Studio e assicurarsi di selezionare Windows 10 SDK durante l'installazione. Se è installato con Visual Studio, il compilatore locale U-SQL lo troverà automaticamente.
- Installare gli Strumenti Data Lake per Visual Studio. È possibile trovare i file di Visual C++ e Windows SDK preconfezionati in C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.
  
  In questo caso, il compilatore locale U-SQL non riesce a trovare automaticamente le dipendenze. È necessario specificare il percorso del CppSDK. È possibile copiare i file in un'altra posizione o usarli così come sono.

Comprendere i concetti di base

Radice dei dati

La cartella data-root è un "archivio locale" per l'account di calcolo locale. Equivale all'account Azure Data Lake Store di un account Data Lake Analytics. Il passaggio a una cartella data-root diversa equivale a passare a un account di archivio diverso. Se si desidera accedere ai dati comunemente condivisi con cartelle radice dei dati diverse, è necessario usare percorsi assoluti negli script. In alternativa, creare collegamenti simbolici del file system (ad esempio, mklink in NTFS) nella cartella data-root per puntare ai dati condivisi.

La cartella data-root viene usata per:

Archiviare i metadati locali, inclusi database, tabelle, funzioni con valori di tabella e assembly.
Cercare i percorsi di input e output definiti come percorsi relativi in U-SQL. L'uso di percorsi relativi semplifica la distribuzione dei progetti U-SQL in Azure.

Percorso del file in U-SQL

È possibile usare sia un percorso relativo che un percorso assoluto locale negli script U-SQL. Il percorso relativo è relativo al percorso della cartella data-root specificato. È consigliabile usare "/" come separatore di percorso per rendere gli script compatibili con il lato server. Ecco alcuni esempi di percorsi relativi e i relativi percorsi assoluti equivalenti. In questi esempi C:\LocalRunDataRoot è la cartella data-root.

Percorso relativo	Percorso assoluto
/abc/def/input.csv	C:\LocalRunDataRoot\abc\def\input.csv
abc/def/input.csv	C:\LocalRunDataRoot\abc\def\input.csv
D:/abc/def/input.csv	D:\abc\def\input.csv

Directory di lavoro

Quando si esegue lo script U-SQL in locale, viene creata una directory di lavoro durante la compilazione nella directory in esecuzione corrente. Oltre agli output di compilazione, i file di runtime necessari per l'esecuzione locale verranno copiati in questa directory di lavoro. La cartella radice della directory di lavoro è denominata "ScopeWorkDir" e i file nella directory di lavoro sono i seguenti:

Directory/file	Directory/file	Directory/file	Definizione	Descrizione
C6A101DDCB470506			Stringa hash della versione di runtime	Copia shadow dei file di runtime necessari per l'esecuzione locale
	Script_66AE4909AA0ED06C		Nome script e stringa hash del percorso dello script	Output di compilazione e registrazione dei passaggi di esecuzione
		_script_.abr	Output del compilatore	File di algebra
		_ScopeCodeGen_.*	Output del compilatore	Codice gestito generato
		_ScopeCodeGenEngine_.*	Output del compilatore	Codice nativo generato
		assembly a cui si fa riferimento	riferimento all'assembly	File di assembly a cui si fa riferimento
		risorse distribuite	Distribuzione delle risorse	File di distribuzione delle risorse
		xxxxxxxx.xxx[1..n]_.	Registro di esecuzione	Log dei passaggi di esecuzione

Usare l'SDK dalla riga di comando

Interfaccia della riga di comando dell'applicazione helper

Nella directory\build\runtime, LocalRunHelper.exe dell'SDK è l'applicazione di supporto della riga di comando che fornisce interfacce alla maggior parte delle funzioni per l'esecuzione locale comunemente usate. Sia il comando che gli interruttori di argomento sono sensibili alle maiuscole. Per richiamarlo:

LocalRunHelper.exe <command> <Required-Command-Arguments> [Optional-Command-Arguments]

Eseguire LocalRunHelper.exe senza argomenti o con l'opzione help per visualizzare le informazioni di aiuto.

> LocalRunHelper.exe help
    Command 'help' :  Show usage information
    Command 'compile' :  Compile the script
    Required Arguments :
        -Script param
                Script File Path
    Optional Arguments :
        -Shallow [default value 'False']
                Shallow compile

Nelle informazioni della Guida:

comando mostra il nome del comando.
argomento obbligatorio elenca gli argomenti che devono essere forniti.
argomento facoltativo elenca gli argomenti facoltativi, con valori predefiniti. Gli argomenti booleani facoltativi non hanno parametri e la loro presenza indica un valore contrario al valore predefinito.

Valore restituito e registrazione

L'applicazione helper restituisce 0 per esito positivo e -1 in caso di errore. Per impostazione predefinita, l'helper invia tutti i messaggi alla console corrente. Tuttavia, la maggior parte dei comandi supporta il -MessageOut path_to_log_file argomento facoltativo che reindirizza gli output a un file di log.

Configurazione delle variabili di ambiente

L'esecuzione locale di U-SQL richiede una radice dati specificata come account di archiviazione locale e un percorso CppSDK specificato per le dipendenze. È possibile impostare sia l'argomento nella riga di comando sia la variabile di ambiente per essi.

Impostare la variabile di ambiente SCOPE_CPP_SDK.

Se si ottiene Microsoft Visual C++ e Windows SDK installando Data Lake Tools per Visual Studio, verificare di avere la cartella seguente:

C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\Microsoft Azure Data Lake Tools for Visual Studio 2015\X.X.XXXX.X\CppSDK

Definire una nuova variabile di ambiente denominata SCOPE_CPP_SDK in modo che punti a questa directory. In alternativa, copiare la cartella nell'altra posizione e specificare SCOPE_CPP_SDK come tale.

Oltre a impostare la variabile di ambiente, è possibile specificare l'argomento -CppSDK quando si usa la riga di comando. Questo argomento sostituisce la variabile di ambiente CppSDK predefinita.
Impostare la variabile di ambiente LOCALRUN_DATAROOT.

Definire una nuova variabile di ambiente denominata LOCALRUN_DATAROOT che punta alla radice dei dati.

Oltre a impostare la variabile di ambiente, è possibile specificare l'argomento -DataRoot con il percorso data-root quando si usa una riga di comando. Questo argomento sovrascrive la variabile ambiente di data-root predefinita. È necessario aggiungere questo argomento a ogni riga di comando in esecuzione in modo da poter sovrascrivere la variabile di ambiente data-root predefinita per tutte le operazioni.

Esempi di utilizzo della riga di comando sdk

Compila ed esegui

Il eseguire comando viene usato per compilare lo script e quindi eseguire i risultati compilati. Gli argomenti della riga di comando sono una combinazione di quelli di compilazione e esecuzione.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

Di seguito sono elencati gli argomenti facoltativi per eseguire:

Argomentazione	Valore predefinito	Descrizione
-CodeBehind	Falso	Il script ha codice dietro .cs
-CppSDK		CppSDK Directory
-DataRoot	Variabile di ambiente DataRoot	DataRoot per l'esecuzione locale, predefinito alla variabile di ambiente "LOCALRUN_DATAROOT"
-MessageOut		Salvare i messaggi dalla console in un file
-Parallelo	1	Esegui il piano con il parallelismo specificato
-Referenze		Elenco di percorsi verso assembly di riferimento aggiuntivi o file di dati del codice sottostante, separati da ';'
-UdoRedirect	Falso	Creare la configurazione di reindirizzamento dell'assembly Udo
-UsaDatabase	maestro	Database da utilizzare per l'assembly code-behind della registrazione temporanea
-Verboso	Falso	Visualizzare output dettagliati dal runtime
-WorkDir	Cartella corrente	Directory per l'utilizzo e gli output del compilatore
-RunScopeCEP	0	Modalità da usare per ScopeCEP
-ScopeCEPTempPath	temperatura	Percorso temporaneo da usare per lo streaming dei dati
-OptFlags		Elenco di opzioni di ottimizzazione separate da virgole

Ecco un esempio:

LocalRunHelper run -Script d:\test\test1.usql -WorkDir d:\test\bin -CodeBehind -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB –Parallel 5 -Verbose

Oltre a combinare compilare e eseguire, è possibile compilare ed eseguire i file eseguibili separatamente.

Compilare uno script U-SQL

Il comando di compilazione viene usato per compilare uno script U-SQL in file eseguibili.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Di seguito sono riportati argomenti facoltativi per compilare:

Argomentazione	Descrizione
-CodeBehind [valore predefinito 'Falso']	Il script ha codice dietro .cs
-CppSDK [valore predefinito '']	CppSDK Directory
-DataRoot [valore predefinito 'Variabile di ambiente DataRoot']	DataRoot per l'esecuzione locale, predefinito alla variabile di ambiente "LOCALRUN_DATAROOT"
-MessageOut [valore predefinito '']	Salvare i messaggi dalla console in un file
-References [valore predefinito '']	Elenco di percorsi verso assembly di riferimento aggiuntivi o file di dati del codice sottostante, separati da ';'
-Superficiale [valore predefinito 'Falso']	Compilazione parziale
-UdoRedirect [valore predefinito 'False']	Creare la configurazione di reindirizzamento dell'assembly Udo
-UseDatabase [valore predefinito 'master']	Database da utilizzare per l'assembly code-behind della registrazione temporanea
-WorkDir [valore predefinito 'Current Directory']	Directory per l'utilizzo e gli output del compilatore
-RunScopeCEP [valore predefinito '0']	Modalità ScopeCEP da utilizzare
-ScopeCEPTempPath [valore predefinito 'temp']	Percorso temporaneo da usare per lo streaming dei dati
-OptFlags [valore predefinito '']	Elenco di opzioni di ottimizzazione separate da virgole

Ecco alcuni esempi di utilizzo.

Eseguire la compilazione di uno script U-SQL:

LocalRunHelper compile -Script d:\test\test1.usql

Compilare uno script U-SQL e impostare la cartella data-root. Questa operazione sovrascriverà la variabile di ambiente impostata.

LocalRunHelper compile -Script d:\test\test1.usql –DataRoot c:\DataRoot

Compilare uno script U-SQL e impostare una directory di lavoro, un assembly di riferimento e un database:

LocalRunHelper compile -Script d:\test\test1.usql -WorkDir d:\test\bin -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB

Eseguire risultati compilati

Il comando execute viene usato per eseguire i risultati compilati.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Di seguito sono riportati gli argomenti facoltativi per eseguire:

Argomentazione	Valore predefinito	Descrizione
-DataRoot	''	Radice di dati per l'esecuzione di metadati. Per impostazione predefinita, viene utilizzata la variabile di ambiente LOCALRUN_DATAROOT.
-MessageOut	''	Trasferisci i messaggi dalla console a un file.
-Parallelo	'1'	Indicatore per eseguire i passaggi di esecuzione locale generati con il livello di parallelismo specificato.
-Verboso	Falso	Indicatore per visualizzare output dettagliati dal runtime.

Ecco un esempio d'uso:

LocalRunHelper execute -Algebra d:\test\workdir\C6A101DDCB470506\Script_66AE4909AA0ED06C\__script__.abr –DataRoot c:\DataRoot –Parallel 5

Usare l'SDK con interfacce di programmazione

Le interfacce di programmazione si trovano tutte nella LocalRunHelper.exe. È possibile usarli per integrare la funzionalità di U-SQL SDK e il framework di test C# per ridimensionare il test locale dello script U-SQL. In questo articolo si userà il progetto di unit test C# standard per illustrare come usare queste interfacce per testare lo script U-SQL.

Passaggio 1: Creare un progetto di unit test C# e la configurazione

Creare un progetto di test di unità C# tramite File > Nuovo > Progetto > Visual C# > Test > Progetto di test di unità.
Aggiungere LocalRunHelper.exe come riferimento per il progetto. Il LocalRunHelper.exe si trova in \build\runtime\LocalRunHelper.exe nel pacchetto NuGet.
U-SQL SDK solo supporta l'ambiente x64, assicurarsi di impostare la destinazione della piattaforma di compilazione come x64. È possibile impostare questa impostazione tramite la proprietà Progetto > piattaforma di destinazione Build >.
Assicurarsi di impostare l'ambiente di test su x64. In Visual Studio, è possibile impostarlo tramite Test > Impostazioni Test > Architettura Predefinita del Processore > x64.
Assicurarsi di copiare tutti i file di dipendenza in NugetPackage\build\runtime\ nella directory di lavoro del progetto, in genere in ProjectFolder\bin\x64\Debug.

Passaggio 2: Creare un test case di script U-SQL

Di seguito è riportato il codice di esempio per il test di script U-SQL. Per i test, è necessario preparare script, file di input e file di output previsti.

using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System.IO;
using System.Text;
using System.Security.Cryptography;
using Microsoft.Analytics.LocalRun;
namespace UnitTestProject1
{
    [TestClass]
    public class USQLUnitTest
    {
        [TestMethod]
        public void TestUSQLScript()
        {
            //Specify the local run message output path
            StreamWriter MessageOutput = new StreamWriter("../../../log.txt");
            LocalRunHelper localrun = new LocalRunHelper(MessageOutput);
            //Configure the DateRoot path, Script Path and CPPSDK path
            localrun.DataRoot = "../../../";
            localrun.ScriptPath = "../../../Script/Script.usql";
            localrun.CppSdkDir = "../../../CppSDK";
            //Run U-SQL script
            localrun.DoRun();
            //Script output
            string Result = Path.Combine(localrun.DataRoot, "Output/result.csv");
            //Expected script output
            string ExpectedResult = "../../../ExpectedOutput/result.csv";
            Test.Helpers.FileAssert.AreEqual(Result, ExpectedResult);
            //Don't forget to close MessageOutput to get logs into file
            MessageOutput.Close();
        }
    }
}
namespace Test.Helpers
{
    public static class FileAssert
    {
        static string GetFileHash(string filename)
        {
            Assert.IsTrue(File.Exists(filename));
            using (var hash = new SHA1Managed())
            {
                var clearBytes = File.ReadAllBytes(filename);
                var hashedBytes = hash.ComputeHash(clearBytes);
                return ConvertBytesToHex(hashedBytes);
            }
        }
        static string ConvertBytesToHex(byte[] bytes)
        {
            var sb = new StringBuilder();
            for (var i = 0; i < bytes.Length; i++)
            {
                sb.Append(bytes[i].ToString("x"));
            }
            return sb.ToString();
        }
        public static void AreEqual(string filename1, string filename2)
        {
            string hash1 = GetFileHash(filename1);
            string hash2 = GetFileHash(filename2);
            Assert.AreEqual(hash1, hash2);
        }
    }
}

Interfacce di programmazione in LocalRunHelper.exe

LocalRunHelper.exe fornisce le interfacce di programmazione per la compilazione locale di U-SQL, l'esecuzione e così via. Le interfacce sono elencate di seguito.

Costruttore

public LocalRunHelper([System.IO.TextWriter messageOutput = null])

Parametro	TIPO	Descrizione
outputMessaggio	System.IO.TextWriter	per i messaggi di output, impostare su null per usare la console

Proprietà

Proprietà	TIPO	Descrizione
AlgebraPath	corda	Percorso del file algebra (file algebra è uno dei risultati della compilazione)
CodeBehindReferences	corda	Se lo script include altri riferimenti code-behind, specifica i percorsi separati con ';'
CppSdkDir	corda	Directory CppSDK
CurrentDir	corda	Directory corrente
DataRoot	corda	Percorso principale dei dati
DebuggerMailPath	corda	Percorso per il mailslot del debugger
GenerateUdoRedirect	bool	Se vogliamo generare una configurazione di override per il reindirizzamento del caricamento degli assembly
HasCodeBehind	bool	Se lo script ha codice sottostante
InputDir	corda	Directory per i dati di input
Percorso del Messaggio	corda	Percorso del file di dump dei messaggi
OutputDir	corda	Directory per i dati di output
Parallelismo	Int	Parallelismo per eseguire l'algebra
ParentPid	Int	PID dell'elemento padre in cui il servizio monitora l'uscita, impostato su 0 o negativo per ignorare
ResultPath	corda	Percorso del file di dump dei risultati
RuntimeDir	corda	Directory di runtime
ScriptPath	corda	Dove trovare lo script
Superficiale	bool	Compilazione superficiale o meno
TempDir	corda	Directory temporanea
UsaDatabase	corda	Specificare il database da utilizzare per la registrazione temporanea dell'assembly del codice sottostante, predefinito come master.
WorkDir	corda	Directory di lavoro preferita

Metodo

Metodo	Descrizione	Ritorno	Parametro
public bool DoCompile()	Compilare lo script U-SQL	True in caso di esito positivo
public bool DoExec()	Eseguire il risultato compilato	Vero in caso di successo
public bool DoRun()	Eseguire lo script U-SQL (Compilazione + Esecuzione)	Vero in caso di esito positivo
public bool IsValidRuntimeDir(string path)	Controllare se il percorso specificato è un percorso di runtime valido	Vero per valido	Percorso della directory di runtime

Domande frequenti sul problema comune

Errore 1

E_CSC_SYSTEM_INTERNAL: Errore interno! Impossibile caricare il file o l'assembly 'ScopeEngineManaged.dll' o una delle relative dipendenze. Il modulo specificato non è stato trovato. (E_CSC_SYSTEM_INTERNAL: errore interno. Impossibile caricare il file o l'assembly 'ScopeEngineManaged.dll' o una delle sue dipendenze. Impossibile trovare il modulo specificato.)

Procedi come segue:

Assicurarsi di avere un ambiente x64. La piattaforma di destinazione della compilazione e l'ambiente di test devono essere x64, vedere Passaggio 1: Creare un progetto di test unitario C# e una configurazione sopra.
Assicurati di aver copiato tutti i file delle dipendenze nella directory di lavoro del progetto in NugetPackage\build\runtime\.

Passaggi successivi

Per informazioni su U-SQL, vedere Introduzione al linguaggio U-SQL di Azure Data Lake Analytics.
Per registrare informazioni di diagnostica, vedere Accesso ai log di diagnostica per Azure Data Lake Analytics.
Per visualizzare una query più complessa, vedere Analizzare i log dei siti Web usando Azure Data Lake Analytics.
Per visualizzare i dettagli del processo, vedere Usare Job Browser e Job View per i processi di Azure Data Lake Analytics.
Per usare la vista di esecuzione dei vertici, vedere Usare la vista di esecuzione dei vertici in Strumenti Data Lake per Visual Studio.

Last updated on 2023-12-20

Condividi tramite