U-SQL uitvoeren en testen met Azure Data Lake U-SQL SDK

Artikel
12/20/2023

Belangrijk

Azure Data Lake Analytics op 29 februari 2024 buiten gebruik gesteld. Meer informatie over deze aankondiging.

Voor gegevensanalyse kan uw organisatie gebruikmaken van Azure Synapse Analytics of Microsoft Fabric.

Bij het ontwikkelen van een U-SQL-script is het gebruikelijk om U-SQL-script lokaal uit te voeren en te testen voordat het naar de cloud wordt verzonden. Azure Data Lake biedt voor dit scenario een NuGet-pakket met de naam Azure Data Lake U-SQL SDK, waarmee u eenvoudig U-SQL-uitvoering kunt schalen en testen. Het is ook mogelijk om deze U-SQL-test te integreren met het CI-systeem (Continuous Integration) om het compileren en testen te automatiseren.

Als u het belangrijk vindt om handmatig lokaal het U-SQL-script uit te voeren en fouten in het U-SQL-script op te sporen met GUI-hulpprogramma's, kunt u hiervoor Azure Data Lake Tools voor Visual Studio gebruiken. Hier vindt u meer informatie.

Azure Data Lake U-SQL SDK installeren

U kunt de Azure Data Lake U-SQL SDK hier downloaden op Nuget.org. En voordat u deze gebruikt, moet u er als volgt voor zorgen dat u afhankelijkheden hebt.

Afhankelijkheden

De Data Lake U-SQL SDK vereist de volgende afhankelijkheden:

Microsoft .NET Framework 4.6 of hoger.
Microsoft Visual C++ 14 en Windows SDK 10.0.10240.0 of hoger (in dit artikel CppSDK genoemd). Er zijn twee manieren om CppSDK op te halen:
- Installeer Visual Studio Community Edition. U hebt de map \Windows Kits\10 onder de map Program Files, bijvoorbeeld C:\Program Files (x86)\Windows Kits\10. U vindt de Windows 10 SDK-versie ook onder \Windows Kits\10\Lib. Als u deze mappen niet ziet, installeert u Visual Studio opnieuw en selecteert u de Windows 10 SDK tijdens de installatie. Als u dit hebt geïnstalleerd met Visual Studio, wordt deze automatisch gevonden door de lokale U-SQL-compiler.
- Installeer Data Lake Tools voor Visual Studio. U vindt de voorverpakte Visual C++ en Windows SDK-bestanden opC:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.
  
  In dit geval kan de lokale U-SQL-compiler de afhankelijkheden niet automatisch vinden. U moet het CppSDK-pad hiervoor opgeven. U kunt de bestanden naar een andere locatie kopiëren of gebruiken zoals ze zijn.

Basisconcepten begrijpen

Hoofdmap van gegevens

De hoofdmap van de gegevens is een 'lokaal archief' voor het lokale rekenaccount. Het is gelijk aan het Azure Data Lake Store-account van een Data Lake Analytics-account. Overschakelen naar een andere hoofdmap voor gegevens is net als overschakelen naar een ander winkelaccount. Als u toegang wilt krijgen tot veelgebruikte gegevens in verschillende hoofdmappen, moet u absolute paden gebruiken in uw scripts. Of maak symbolische koppelingen van het bestandssysteem (bijvoorbeeld mklink op NTFS) onder de hoofdmap gegevens om te verwijzen naar de gedeelde gegevens.

De hoofdmap van de gegevens wordt gebruikt voor het volgende:

Sla lokale metagegevens op, waaronder databases, tabellen, tabelwaardefuncties (TVF's) en assembly's.
Zoek de invoer- en uitvoerpaden op die zijn gedefinieerd als relatieve paden in U-SQL. Door relatieve paden te gebruiken, kunt u uw U-SQL-projecten eenvoudiger implementeren in Azure.

Bestandspad in U-SQL

U kunt zowel een relatief pad als een lokaal absoluut pad gebruiken in U-SQL-scripts. Het relatieve pad is relatief ten opzichte van het opgegeven pad naar de hoofdmap van de gegevens. U wordt aangeraden '/' te gebruiken als het padscheidingsteken om uw scripts compatibel te maken met de serverzijde. Hier volgen enkele voorbeelden van relatieve paden en hun equivalente absolute paden. In deze voorbeelden is C:\LocalRunDataRoot de map data-root.

Relatief pad	Absoluut pad
/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

Werkmap

Wanneer u het U-SQL-script lokaal uitvoert, wordt er tijdens de compilatie een werkmap gemaakt onder de huidige actieve map. Naast de compilatie-uitvoer worden de benodigde runtimebestanden voor lokale uitvoering schaduw gekopieerd naar deze werkmap. De hoofdmap van de werkmap heet 'ScopeWorkDir' en de bestanden onder de werkmap zijn als volgt:

Map/bestand	Map/bestand	Map/bestand	Definitie	Beschrijving
C6A101DDCB470506			Hash-tekenreeks van runtimeversie	Schaduwkopie van runtimebestanden die nodig zijn voor lokale uitvoering
	Script_66AE4909AA0ED06C		Scriptnaam + hashtekenreeks van scriptpad	Logboekregistratie van compilatie-uitvoer en uitvoeringsstappen
		_script_.abr	Compileruitvoer	Algebra-bestand
		_ScopeCodeGen_.*	Compileruitvoer	Beheerde code gegenereerd
		_ScopeCodeGenEngine_.*	Compileruitvoer	Gegenereerde systeemeigen code
		assembly's waarnaar wordt verwezen	Assembly-verwijzing	Assemblybestanden waarnaar wordt verwezen
		deployed_resources	Resource-implementatie	Resource-implementatiebestanden
		xxxxxxxx.xxx[1..n]_.	Uitvoeringslogboek	Logboek met uitvoeringsstappen

De SDK gebruiken vanaf de opdrachtregel

Opdrachtregelinterface van de helpertoepassing

Onder SDK-directory\build\runtime is LocalRunHelper.exe de opdrachtregelhelpertoepassing die interfaces biedt voor de meeste veelgebruikte functies voor lokaal uitvoeren. Zowel de schakelopties voor opdrachten als argumenten zijn hoofdlettergevoelig. Aanroepen:

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

Voer LocalRunHelper.exe uit zonder argumenten of met de schakeloptie Help om de Help-informatie weer te geven:

> 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

In de Help-informatie:

Opdracht geeft de naam van de opdracht.
Vereist argument bevat argumenten die moeten worden opgegeven.
Optioneel argument bevat optionele argumenten met standaardwaarden. Optionele Booleaanse argumenten hebben geen parameters en hun uiterlijk betekent negatief ten opzichte van de standaardwaarde.

Retourwaarde en logboekregistratie

De helpertoepassing retourneert 0 voor geslaagd en -1 voor fout. Standaard verzendt de helper alle berichten naar de huidige console. De meeste opdrachten ondersteunen echter het path_to_log_file optionele argument -MessageOut waarmee de uitvoer wordt omgeleid naar een logboekbestand.

Configureren van omgevingsvariabele

Lokale uitvoering van U-SQL heeft een opgegeven gegevenshoofdmap nodig als lokaal opslagaccount en een opgegeven CppSDK-pad voor afhankelijkheden. U kunt het argument zowel in de opdrachtregel instellen als de omgevingsvariabele voor hen instellen.

Stel de SCOPE_CPP_SDK omgevingsvariabele in.

Als u Microsoft Visual C++ en de Windows SDK krijgt door Data Lake Tools voor Visual Studio te installeren, controleert u of u de volgende map hebt:

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

Definieer een nieuwe omgevingsvariabele met de naam SCOPE_CPP_SDK om naar deze map te verwijzen. Of kopieer de map naar de andere locatie en geef SCOPE_CPP_SDK zo op.

Naast het instellen van de omgevingsvariabele kunt u het argument -CppSDK opgeven wanneer u de opdrachtregel gebruikt. Met dit argument wordt de standaardomgevingsvariabele CppSDK overschreven.
Stel de LOCALRUN_DATAROOT omgevingsvariabele in.

Definieer een nieuwe omgevingsvariabele met de naam LOCALRUN_DATAROOT die verwijst naar de gegevenshoofdmap.

Naast het instellen van de omgevingsvariabele kunt u het argument -DataRoot opgeven met het pad naar de gegevenshoofdmap wanneer u een opdrachtregel gebruikt. Met dit argument wordt de standaardvariabele data-root-omgeving overschreven. U moet dit argument toevoegen aan elke opdrachtregel die u uitvoert, zodat u de standaard omgevingsvariabele gegevenshoofdmap voor alle bewerkingen kunt overschrijven.

Voorbeelden van sdk-opdrachtregelgebruik

Compileren en uitvoeren

De run-opdracht wordt gebruikt om het script te compileren en vervolgens gecompileerde resultaten uit te voeren. De opdrachtregelargumenten zijn een combinatie van de argumenten van compileren en uitvoeren.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

Hier volgen optionele argumenten voor uitvoeren:

Argument	Standaardwaarde	Beschrijving
-CodeBehind	Niet waar	Het script heeft .cs code achter
-CppSDK		CppSDK-map
-DataRoot	DataRoot-omgevingsvariabele	DataRoot voor lokale uitvoering, standaard ingesteld op omgevingsvariabele 'LOCALRUN_DATAROOT'
-MessageOut		Berichten op de console naar een bestand dumpen
-Parallelle	1	Het plan uitvoeren met de opgegeven parallelle uitvoering
-Verwijzingen		Lijst met paden naar extra referentie-assembly's of gegevensbestanden met code erachter, gescheiden door ';'
-UdoRedirect	Niet waar	Configuratie voor omleiding van Udo-assembly genereren
-UseDatabase	model	Database die moet worden gebruikt voor code achter tijdelijke assembly-registratie
-Uitgebreide	False	Gedetailleerde uitvoer van runtime weergeven
-WorkDir	Huidige map	Map voor compilergebruik en -uitvoer
-RunScopeCEP	0	Te gebruiken ScopeCEP-modus
-ScopeCEPTempPath	temp	Tijdelijk pad dat moet worden gebruikt voor het streamen van gegevens
-OptFlags		Door komma's gescheiden lijst met optimalisatievlaggetjes

Hier volgt een voorbeeld:

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

Naast het combineren van compileren en uitvoeren, kunt u de gecompileerde uitvoerbare bestanden afzonderlijk compileren en uitvoeren.

Een U-SQL-script compileren

De compileeropdracht wordt gebruikt om een U-SQL-script te compileren naar uitvoerbare bestanden.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Hier volgen optionele argumenten voor compileren:

Argument	Description
-CodeBehind [standaardwaarde 'False']	Het script heeft .cs code achter
-CppSDK [standaardwaarde '']	CppSDK-map
-DataRoot [standaardwaarde 'DataRoot environment variable']	DataRoot voor lokale uitvoering, standaard ingesteld op omgevingsvariabele 'LOCALRUN_DATAROOT'
-MessageOut [standaardwaarde '']	Berichten op de console naar een bestand dumpen
-Verwijzingen [standaardwaarde '']	Lijst met paden naar extra referentie-assembly's of gegevensbestanden met code erachter, gescheiden door ';'
-Shallow [standaardwaarde 'False']	Ondiep compileren
-UdoRedirect [standaardwaarde 'False']	Configuratie voor omleiding van Udo-assembly genereren
-UseDatabase [standaardwaarde 'master']	Database die moet worden gebruikt voor code achter tijdelijke assembly-registratie
-WorkDir [standaardwaarde 'Current Directory']	Map voor compilergebruik en -uitvoer
-RunScopeCEP [standaardwaarde '0']	Te gebruiken ScopeCEP-modus
-ScopeCEPTempPath [standaardwaarde 'temp']	Tijdelijk pad dat moet worden gebruikt voor het streamen van gegevens
-OptFlags [standaardwaarde '']	Door komma's gescheiden lijst met optimalisatievlaggetjes

Hier volgen enkele gebruiksvoorbeelden.

Compileer een U-SQL-script:

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

Compileer een U-SQL-script en stel de map data-root in. Hiermee wordt de ingestelde omgevingsvariabele overschreven.

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

Compileer een U-SQL-script en stel een werkmap, referentieassembly en database in:

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

Gecompileerde resultaten uitvoeren

De opdracht execute wordt gebruikt om gecompileerde resultaten uit te voeren.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Hier volgen optionele argumenten voor uitvoering:

Argument	Standaardwaarde	Beschrijving
-DataRoot	''	Gegevenshoofdmap voor het uitvoeren van metagegevens. De standaardinstelling is de omgevingsvariabele LOCALRUN_DATAROOT .
-MessageOut	''	Berichten op de console dumpen naar een bestand.
-Parallelle	'1'	Indicator voor het uitvoeren van de gegenereerde stappen voor lokaal uitvoeren met het opgegeven parallelle uitvoeringsniveau.
-Uitgebreide	'Onwaar'	Indicator om gedetailleerde uitvoer van runtime weer te geven.

Hier volgt een gebruiksvoorbeeld:

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

De SDK gebruiken met programmeerinterfaces

De programmeerinterfaces bevinden zich allemaal in de LocalRunHelper.exe. U kunt deze gebruiken om de functionaliteit van de U-SQL SDK en het C#-testframework te integreren om de lokale test van uw U-SQL-script te schalen. In dit artikel gebruik ik het standaard C#-eenheidstestproject om te laten zien hoe u deze interfaces kunt gebruiken om uw U-SQL-script te testen.

Stap 1: Testproject en configuratie voor C#-eenheden maken

Maak een C#-eenheidstestproject via File > New > Project > Visual C# > Test > Unit Test Project.
Voeg LocalRunHelper.exe toe als referentie voor het project. De LocalRunHelper.exe bevindt zich op \build\runtime\LocalRunHelper.exe in NuGet-pakket.
U-SQL SDK ondersteunt alleen de x64-omgeving. Zorg ervoor dat u het buildplatformdoel instelt op x64. U kunt dit instellen via het doel Build > Platform van projecteigenschap>.
Zorg ervoor dat u uw testomgeving instelt als x64. In Visual Studio kunt u dit instellen via Test > testinstellingen > Standaardprocessorarchitectuur > x64.
Zorg ervoor dat u alle afhankelijkheidsbestanden onder NugetPackage\build\runtime\ kopieert naar de projectwerkmap, meestal onder ProjectFolder\bin\x64\Debug.

Stap 2: testcase voor U-SQL-script maken

Hieronder ziet u de voorbeeldcode voor de U-SQL-scripttest. Voor het testen moet u scripts, invoerbestanden en verwachte uitvoerbestanden voorbereiden.

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

Programmeerinterfaces in LocalRunHelper.exe

LocalRunHelper.exe biedt de programmeerinterfaces voor lokaal compileren, uitvoeren, enzovoort van U-SQL. De interfaces worden als volgt weergegeven.

Constructor

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

Parameter	Type	Description
messageOutput	System.IO.TextWriter	voor uitvoerberichten, ingesteld op null om console te gebruiken

Eigenschappen

Eigenschap	Type	Description
AlgebraPath	tekenreeks	Het pad naar het algebra-bestand (algebrabestand is een van de compilatieresultaten)
CodeBehindReferences	tekenreeks	Als het script andere code achter verwijzingen bevat, geeft u de paden op die zijn gescheiden met ';'
CppSdkDir	tekenreeks	CppSDK-map
CurrentDir	tekenreeks	Huidige map
DataRoot	tekenreeks	Pad naar de hoofdmap van gegevens
FoutopsporingsprogrammaMailPath	tekenreeks	Het pad naar het foutopsporingsprogramma mailslot
GenerateUdoRedirect	booleaans	Als we omleiding voor het laden van assembly's willen genereren, overschrijft u de configuratie
HasCodeBehind	booleaans	Als het script code achter zich heeft
InputDir	tekenreeks	Map voor invoergegevens
MessagePath	tekenreeks	Pad naar berichtdumpbestand
OutputDir	tekenreeks	Map voor uitvoergegevens
Parallelle uitvoering	int	Parallellisme om de algebra uit te voeren
ParentPid	int	PID van het bovenliggende item waarop de service controleert om af te sluiten, ingesteld op 0 of negatief om te negeren
ResultPath	tekenreeks	Bestandspad voor resultaatdump
RuntimeDir	tekenreeks	Runtime-map
ScriptPath	tekenreeks	Waar u het script kunt vinden
Ondiepe	booleaans	Ondiep compileren of niet
Tempdir	tekenreeks	Tijdelijke map
UseDataBase	tekenreeks	Geef de database op die moet worden gebruikt voor code achter de tijdelijke assembly-registratie, standaard master
WorkDir	tekenreeks	Voorkeurswerkmap

Methode

Methode	Beschrijving	Retourneren	Parameter
public bool DoCompile()	Het U-SQL-script compileren	Waar bij succes
public bool DoExec()	Het gecompileerde resultaat uitvoeren	Waar bij succes
openbare bool DoRun()	Het U-SQL-script uitvoeren (compileren en uitvoeren)	Waar bij succes
public bool IsValidRuntimeDir(tekenreekspad)	Controleer of het opgegeven pad een geldig runtimepad is	Waar voor geldig	Het pad van de runtimemap

Veelgestelde vragen over veelvoorkomende problemen

Fout 1

E_CSC_SYSTEM_INTERNAL: Interne fout! Kan bestand of assembly 'ScopeEngineManaged.dll' of een van de afhankelijkheden niet laden. De opgegeven module is niet gevonden.

Controleer het volgende:

Zorg ervoor dat u een x64-omgeving hebt. Het builddoelplatform en de testomgeving moeten x64 zijn. Raadpleeg stap 1: testproject en configuratie voor C#-eenheden maken hierboven.
Zorg ervoor dat u alle afhankelijkheidsbestanden onder NugetPackage\build\runtime\ hebt gekopieerd naar de projectwerkmap.

Volgende stappen

Zie Aan de slag met de Azure Data Lake Analytics U-SQL-taal om U-SQL te leren.
Zie Toegang tot diagnostische logboeken voor Azure Data Lake Analytics om diagnostische gegevens te registreren.
Zie Websitelogboeken analyseren met Behulp van Azure Data Lake Analytics voor een complexere query.
Zie Taakbrowser en Taakweergave gebruiken voor Azure Data Lake Analytics-taken om taakdetails weer te geven.
Zie De uitvoeringsweergave voor hoekpunten gebruiken in Data Lake Tools voor Visual Studio als u de uitvoeringsweergave voor hoekpunten wilt gebruiken.