Spouštění a testování U-SQL pomocí sady Azure Data Lake U-SQL SDK

Článek
12/20/2023

Důležité

Azure Data Lake Analytics vyřazena 29. února 2024. Další informace najdete v tomto oznámení.

K analýze dat může vaše organizace použít Azure Synapse Analytics nebo Microsoft Fabric.

Při vývoji skriptu U-SQL je běžné spouštět a testovat skript U-SQL místně před jeho odesláním do cloudu. Azure Data Lake poskytuje pro tento scénář balíček NuGet s názvem Azure Data Lake U-SQL SDK, pomocí kterého můžete snadno škálovat spuštění a testování U-SQL. Tento test U-SQL je také možné integrovat se systémem kontinuální integrace (CI) a automatizovat tak kompilaci a testování.

Pokud vám záleží na tom, jak ručně místně spustit a ladit skript U-SQL pomocí nástrojů grafického uživatelského rozhraní, můžete k tomu použít Nástroje Azure Data Lake pro Visual Studio. Další informace najdete tady.

Instalace sady Azure Data Lake U-SQL SDK

Sadu Azure Data Lake U-SQL SDK můžete získat tady na Nuget.org. A před použitím se musíte ujistit, že máte závislosti, jak je uvedeno níže.

Závislosti

Sada Data Lake U-SQL SDK vyžaduje následující závislosti:

Microsoft .NET Framework 4.6 nebo novější.
Microsoft Visual C++ 14 a Windows SDK 10.0.10240.0 nebo novější (která se v tomto článku nazývá CppSDK). CppSDK získáte dvěma způsoby:
- Nainstalujte Visual Studio Community Edition. Ve složce Program Files budete mít složku \Windows Kits\10, například C:\Program Files (x86)\Windows Kits\10. Verzi sady Windows 10 SDK najdete také v části \Windows Kits\10\Lib. Pokud tyto složky nevidíte, přeinstalujte sadu Visual Studio a nezapomeňte během instalace vybrat sadu Windows 10 SDK. Pokud ho máte nainstalovaný se sadou Visual Studio, místní kompilátor U-SQL ho automaticky najde.
- Nainstalujte nástroje Data Lake pro Visual Studio. Předem zabalené soubory Visual C++ a Windows SDK najdete na adreseC:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.
  
  V tomto případě místní kompilátor U-SQL nemůže najít závislosti automaticky. Musíte pro něj zadat cestu CppSDK. Soubory můžete buď zkopírovat do jiného umístění, nebo je použít tak, jak jsou.

Vysvětlení základních konceptů

Kořen dat

Kořenová složka dat je "místní úložiště" pro místní výpočetní účet. Je ekvivalentní účtu Azure Data Lake Store účtu Data Lake Analytics. Přepnutí do jiné složky kořenového adresáře dat se podobá přepnutí do jiného účtu úložiště. Pokud chcete přistupovat k běžně sdíleným datům pomocí různých kořenových složek dat, musíte ve skriptech použít absolutní cesty. Nebo vytvořte symbolické odkazy systému souborů (například mklink v systému souborů NTFS) ve složce kořenového adresáře dat, které budou odkazovat na sdílená data.

Kořenová složka dat slouží k:

Ukládat místní metadata, včetně databází, tabulek, funkcí TVF (Table-Valued) a sestavení.
Vyhledejte vstupní a výstupní cesty, které jsou definované jako relativní cesty v U-SQL. Použití relativních cest usnadňuje nasazení projektů U-SQL do Azure.

Cesta k souboru v U-SQL

Ve skriptech U-SQL můžete použít relativní cestu i absolutní místní cestu. Relativní cesta je relativní vzhledem k zadané cestě ke kořenové složce dat. Jako oddělovač cesty doporučujeme použít "/", aby byly vaše skripty kompatibilní se serverovou stranou. Tady je několik příkladů relativních cest a jejich ekvivalentních absolutních cest. V těchto příkladech je složka kořenového adresáře dat C:\LocalRunDataRoot.

Relativní cesta	Absolutní cesta
/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

Pracovní adresář

Při místním spuštění skriptu U-SQL se v aktuálním spuštěném adresáři vytvoří během kompilace pracovní adresář. Kromě výstupů kompilace budou do tohoto pracovního adresáře stínové zkopírovány soubory modulu runtime potřebné pro místní spuštění. Kořenová složka pracovního adresáře má název ScopeWorkDir a soubory v pracovním adresáři jsou následující:

Adresář nebo soubor	Adresář nebo soubor	Adresář nebo soubor	Definice	Popis
C6A101DDCB470506			Řetězec hash verze modulu runtime	Stínová kopie souborů modulu runtime potřebných pro místní spuštění
	Script_66AE4909AA0ED06C		Název skriptu + řetězec hash cesty ke skriptu	Výstupy kompilace a protokolování kroků spuštění
		_script_.abr	Výstup kompilátoru	Soubor Algebra
		_ScopeCodeGen_.*	Výstup kompilátoru	Vygenerovaný spravovaný kód
		_ScopeCodeGenEngine_.*	Výstup kompilátoru	Vygenerovaný nativní kód
		odkazovaná sestavení	Odkaz na sestavení	Odkazované soubory sestavení
		deployed_resources	Nasazení prostředků	Soubory nasazení prostředků
		xxxxxxxx.xxx[1..n]_.	Protokol spuštění	Protokol kroků spuštění

Použití sady SDK z příkazového řádku

Rozhraní příkazového řádku pomocné aplikace

V části SDK directory\build\runtime je LocalRunHelper.exe pomocná aplikace příkazového řádku, která poskytuje rozhraní pro většinu běžně používaných funkcí místního spuštění. U přepínačů příkazů i argumentů se rozlišují velká a malá písmena. Vyvolání:

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

Spuštěním LocalRunHelper.exe bez argumentů nebo s přepínačem nápovědy zobrazte informace o nápovědě:

> 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

V informacích nápovědy:

Příkaz vrátí název příkazu.
Povinný argument uvádí argumenty, které je nutné zadat.
Nepovinný argument vypíše argumenty, které jsou volitelné, s výchozími hodnotami. Volitelné logické argumenty nemají parametry a jejich vzhled znamená zápornou výchozí hodnotu.

Návratová hodnota a protokolování

Pomocná aplikace vrátí 0 pro úspěch a -1 pro selhání. Ve výchozím nastavení odesílá pomocná rutina všechny zprávy do aktuální konzoly. Většina příkazů však podporuje -MessageOut path_to_log_file volitelný argument, který přesměruje výstupy do souboru protokolu.

Konfigurace proměnné prostředí

Místní spuštění U-SQL vyžaduje zadaný kořen dat jako účet místního úložiště a zadanou cestu CppSDK pro závislosti. Argument můžete nastavit v příkazovém řádku nebo proměnnou prostředí.

Nastavte SCOPE_CPP_SDK proměnnou prostředí.

Pokud Microsoft Visual C++ a Windows SDK získáte instalací nástrojů Data Lake pro Visual Studio, ověřte, že máte následující složku:

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

Definujte novou proměnnou prostředí s názvem SCOPE_CPP_SDK , která bude odkazovat na tento adresář. Nebo složku zkopírujte do jiného umístění a zadejte SCOPE_CPP_SDK .

Kromě nastavení proměnné prostředí můžete při použití příkazového řádku zadat argument -CppSDK . Tento argument přepíše výchozí proměnnou prostředí CppSDK.
Nastavte LOCALRUN_DATAROOT proměnnou prostředí.

Definujte novou proměnnou prostředí s názvem LOCALRUN_DATAROOT , která odkazuje na kořen dat.

Kromě nastavení proměnné prostředí můžete při použití příkazového řádku zadat argument -DataRoot s cestou kořene dat. Tento argument přepíše výchozí proměnnou prostředí kořenového adresáře dat. Tento argument musíte přidat do každého příkazového řádku, který spouštíte, abyste mohli přepsat výchozí proměnnou prostředí kořene dat pro všechny operace.

Ukázky použití příkazového řádku SDK

Kompilace a spuštění

Příkaz run slouží ke kompilaci skriptu a následnému spuštění zkompilovaných výsledků. Jeho argumenty příkazového řádku jsou kombinací argumentů z kompilace a spuštění.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

Toto jsou volitelné argumenty pro spuštění:

Argument	Výchozí hodnota	Description
-Codebehind	Ne	Skript obsahuje .cs kód.
-CppSDK		Adresář CppSDK
-DataRoot	Proměnná prostředí DataRoot	DataRoot pro místní spuštění, výchozí proměnná prostředí LOCALRUN_DATAROOT
-MessageOut		Výpis zpráv na konzole do souboru
-Paralelní	1	Spuštění plánu se zadaným paralelismem
-Odkazy		Seznam cest k nadbytečným referenčním sestavením nebo datovým souborům kódu, oddělených znakem ;.
-UdoRedirect	Ne	Generování konfigurace přesměrování sestavení Udo
-UseDatabase	master	Databáze, která se má použít pro kód za dočasnou registrací sestavení
-Podrobné	Ne	Zobrazení podrobných výstupů z modulu runtime
-WorkDir	Aktuální adresář	Adresář pro použití a výstupy kompilátoru
-RunScopeCEP	0	Režim ScopeCEP, který se má použít
-ScopeCEPTempPath	temp	Dočasná cesta pro streamování dat
-OptFlags		Čárkami oddělený seznam příznaků optimalizátoru

Tady je příklad:

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

Kromě kombinování příkazu compile a execute můžete kompilovat a spouštět zkompilované spustitelné soubory samostatně.

Kompilace skriptu U-SQL

Příkaz compile slouží ke kompilaci skriptu U-SQL do spustitelných souborů.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Následující argumenty jsou volitelné pro kompilaci:

Argument	Description
-CodeBehind [výchozí hodnota 'False']	Skript obsahuje .cs kód.
-CppSDK [výchozí hodnota '']	Adresář CppSDK
-DataRoot [výchozí hodnota 'DataRoot proměnná prostředí']	DataRoot pro místní spuštění, výchozí proměnná prostředí LOCALRUN_DATAROOT
-MessageOut [výchozí hodnota '']	Výpis zpráv na konzole do souboru
-References [výchozí hodnota '']	Seznam cest k nadbytečným referenčním sestavením nebo datovým souborům kódu, oddělených znakem ;.
-Shallow [výchozí hodnota "False"]	Mělký kompilační
-UdoRedirect [výchozí hodnota False]]	Generování konfigurace přesměrování sestavení Udo
-UseDatabase [výchozí hodnota 'master']	Databáze, která se má použít pro kód za dočasnou registrací sestavení
-WorkDir [výchozí hodnota 'Current Directory']	Adresář pro použití a výstupy kompilátoru
-RunScopeCEP [výchozí hodnota '0']	Režim ScopeCEP, který se má použít
-ScopeCEPTempPath [výchozí hodnota 'temp']	Dočasná cesta pro streamování dat
-OptFlags [výchozí hodnota '']	Čárkami oddělený seznam příznaků optimalizátoru

Tady je několik příkladů použití.

Kompilace skriptu U-SQL:

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

Zkompilujte skript U-SQL a nastavte složku kořenového adresáře dat. Tím se přepíše nastavená proměnná prostředí.

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

Zkompilujte skript U-SQL a nastavte pracovní adresář, referenční sestavení a databázi:

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

Spuštění zkompilovaných výsledků

Příkaz execute se používá ke spuštění zkompilovaných výsledků.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Následují volitelné argumenty pro provedení:

Argument	Výchozí hodnota	Description
-DataRoot	''	Kořen dat pro provádění metadat. Výchozí hodnota je proměnná prostředí LOCALRUN_DATAROOT .
-MessageOut	''	Výpis zpráv v konzole do souboru.
-Paralelní	'1'	Indikátor pro spuštění vygenerovaných kroků místního spuštění se zadanou úrovní paralelismu.
-Podrobné	Nepravda	Indikátor pro zobrazení podrobných výstupů z modulu runtime

Tady je příklad použití:

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

Použití sady SDK s programovacími rozhraními

Všechna programovací rozhraní se nacházejí v LocalRunHelper.exe. Můžete je použít k integraci funkcí sady U-SQL SDK a testovací architektury jazyka C# pro škálování místního testu skriptu U-SQL. V tomto článku pomocí standardního projektu testování jednotek V jazyce C# ukážu, jak pomocí těchto rozhraní otestovat skript U-SQL.

Krok 1: Vytvoření projektu a konfigurace testování jednotek v jazyce C#

Vytvořte projekt testování jednotek jazyka C# prostřednictvím nového projektu > Visual >> C# > Test > Unit Test Project.
Jako referenci pro projekt přidejte LocalRunHelper.exe. LocalRunHelper.exe se nachází v \build\runtime\LocalRunHelper.exe v balíčku NuGet.
Sada U-SQL SDK podporuje pouze prostředí x64. Nezapomeňte nastavit cílovou platformu sestavení jako x64. Můžete ho nastavit prostřednictvím cílové platformy sestavení > vlastností > projektu.
Nezapomeňte nastavit testovací prostředí jako x64. V sadě Visual Studio ji můžete nastavit prostřednictvím nastavení testovacího > testu > – výchozí architektura procesoru > x64.
Nezapomeňte zkopírovat všechny soubory závislostí v části NugetPackage\build\runtime\ do pracovního adresáře projektu, který je obvykle ve složce ProjectFolder\bin\x64\Debug.

Krok 2: Vytvoření testovacího případu skriptu U-SQL

Níže je ukázkový kód pro test skriptu U-SQL. Pro testování je potřeba připravit skripty, vstupní soubory a očekávané výstupní soubory.

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);
        }
    }
}

Programovací rozhraní v LocalRunHelper.exe

LocalRunHelper.exe poskytuje programovací rozhraní pro místní kompilaci, spuštění atd. U-SQL. Rozhraní jsou uvedena následujícím způsobem.

Konstruktor

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

Parametr	Typ	Description
messageOutput	System.IO.TextWriter	pro výstupní zprávy nastavte na hodnotu null, aby se používala konzola.

Vlastnosti

Vlastnost	Typ	Description
AlgebraPath	řetězec	Cesta k souboru algebra (soubor algebra je jedním z výsledků kompilace)
CodeBehindReferences	řetězec	Pokud skript obsahuje jiný kód za odkazy, zadejte cesty oddělené znakem ;.
CppSdkDir	řetězec	Adresář CppSDK
CurrentDir	řetězec	Aktuální adresář
Kořenová složka dat	řetězec	Cesta ke kořenovému adresáři dat
Ladicí programMailPath	řetězec	Cesta k mailslotu ladicího programu
GenerateUdoRedirect	bool	Pokud chceme vygenerovat sestavení načítání přesměrování, přepište konfiguraci.
HasCodeBehind	bool	Pokud skript obsahuje kód
InputDir	řetězec	Adresář pro vstupní data
Cesta k zprávě	řetězec	Cesta k souboru výpisu stavu zprávy
Výstupní adresář	řetězec	Adresář pro výstupní data
Paralelnost	int	Paralelismus pro spuštění algebry
ParentPid	int	PID nadřazeného objektu, u kterého služba monitoruje, který se má ukončit, nastavený na hodnotu 0 nebo záporné, pokud se má ignorovat
Cesta výsledku	řetězec	Cesta k souboru výpisu výsledku
RuntimeDir	řetězec	Adresář modulu runtime
Cesta skriptu	řetězec	Kde skript najít
Mělké	bool	Mělká kompilace nebo ne
Tempdir	řetězec	Dočasný adresář
PoužítDataBase	řetězec	Zadejte databázi, která se má použít pro kód za dočasnou registrací sestavení, ve výchozím nastavení hlavní.
Pracovní adresář	řetězec	Upřednostňovaný pracovní adresář

Metoda

Metoda	Popis	Vrácení	Parametr
public bool DoCompile()	Kompilace skriptu U-SQL	Pravda při úspěchu
public bool DoExec()	Spuštění zkompilovaného výsledku	Pravda při úspěchu
public bool DoRun()	Spuštění skriptu U-SQL (kompilace a spuštění)	Pravda při úspěchu
public bool IsValidRuntimeDir(cesta k řetězci)	Zkontrolujte, jestli je daná cesta platná cesta modulu runtime.	Hodnota True pro platné	Cesta k adresáři modulu runtime

Nejčastější dotazy k běžným problémům

Chyba 1

E_CSC_SYSTEM_INTERNAL: Vnitřní chyba! Nelze načíst soubor nebo sestavení "ScopeEngineManaged.dll" nebo jednu z jejich závislostí. Zadaný modul nebyl nalezen.

Zkontrolujte následující:

Ujistěte se, že máte prostředí x64. Cílová platforma sestavení a testovací prostředí by měly být x64. Viz Krok 1: Vytvoření projektu a konfigurace testování jednotek V C# výše.
Ujistěte se, že jste zkopírovali všechny soubory závislostí v části NugetPackage\build\runtime\ do pracovního adresáře projektu.

Další kroky

Pokud se chcete naučit jazyk U-SQL, informace najdete v tématu Začínáme s jazykem U-SQL Azure Data Lake Analytics.
Informace o protokolování diagnostiky najdete v tématu Přístup k diagnostickým protokolům pro Azure Data Lake Analytics.
Pokud chcete zobrazit složitější dotaz, přečtěte si téma Analýza webových protokolů pomocí Azure Data Lake Analytics.
Pokud chcete zobrazit podrobnosti o úloze, přečtěte si téma Použití prohlížeče úloh a zobrazení úloh pro úlohy Azure Data Lake Analytics.
Pokud chcete použít zobrazení spouštění vrcholů, přečtěte si téma Použití zobrazení spouštění vrcholů v nástrojích Data Lake pro Visual Studio.