Köra och testa U-SQL med Azure Data Lake U-SQL SDK
Viktigt
Azure Data Lake Analytics drog sig tillbaka den 29 februari 2024. Läs mer med det här meddelandet.
För dataanalys kan din organisation använda Azure Synapse Analytics eller Microsoft Fabric.
När du utvecklar U-SQL-skript är det vanligt att köra och testa U-SQL-skript lokalt innan du skickar det till molnet. Azure Data Lake tillhandahåller ett NuGet-paket med namnet Azure Data Lake U-SQL SDK för det här scenariot, där du enkelt kan skala U-SQL-körning och -test. Det går också att integrera det här U-SQL-testet med CI-systemet (kontinuerlig integrering) för att automatisera kompilering och testning.
Om du bryr dig om hur du manuellt kör och felsöker U-SQL-skript med GUI-verktyg kan du använda Azure Data Lake Tools för Visual Studio för det. Du kan lära dig mer härifrån.
Installera Azure Data Lake U-SQL SDK
Du kan hämta Azure Data Lake U-SQL SDK här på Nuget.org. Och innan du använder det måste du se till att du har beroenden på följande sätt.
Beroenden
Data Lake U-SQL SDK kräver följande beroenden:
Microsoft Visual C++ 14 och Windows SDK 10.0.10240.0 eller senare (som kallas CppSDK i den här artikeln). Det finns två sätt att hämta CppSDK:
Installera Visual Studio Community Edition. Du har en \Windows Kits\10-mapp under mappen Programfiler, till exempel C:\Program Files (x86)\Windows Kits\10. Du hittar även Windows 10 SDK-versionen under \Windows Kits\10\Lib. Om du inte ser dessa mappar installerar du om Visual Studio och väljer Windows 10 SDK under installationen. Om du har det installerat med Visual Studio hittar den lokala U-SQL-kompilatorn den automatiskt.
Installera Data Lake Tools för Visual Studio. Du hittar förpaketerade Visual C++ och Windows SDK filer på
C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.I det här fallet kan den lokala U-SQL-kompilatorn inte hitta beroendena automatiskt. Du måste ange CppSDK-sökvägen för den. Du kan antingen kopiera filerna till en annan plats eller använda dem som de är.
Förstå grundläggande begrepp
Datarot
Datarotsmappen är ett "lokalt arkiv" för det lokala beräkningskontot. Det motsvarar Azure Data Lake Store-kontot för ett Data Lake Analytics konto. Att växla till en annan datarotsmapp är precis som att byta till ett annat lagringskonto. Om du vill komma åt vanliga delade data med olika datarotsmappar måste du använda absoluta sökvägar i skripten. Eller skapa symboliska länkar för filsystemet (till exempel mklink på NTFS) under mappen datarot för att peka på delade data.
Datarotsmappen används för att:
- Lagra lokala metadata, inklusive databaser, tabeller, tabellvärdesfunktioner (TVF:er) och sammansättningar.
- Leta upp de indata- och utdatasökvägar som definieras som relativa sökvägar i U-SQL. Med relativa sökvägar blir det enklare att distribuera dina U-SQL-projekt till Azure.
Filsökväg i U-SQL
Du kan använda både en relativ sökväg och en lokal absolut sökväg i U-SQL-skript. Den relativa sökvägen är relativ till den angivna sökvägen till datarotsmappen. Vi rekommenderar att du använder "/" som sökvägsavgränsare för att göra skripten kompatibla med serversidan. Här är några exempel på relativa sökvägar och motsvarande absoluta sökvägar. I de här exemplen är C:\LocalRunDataRoot mappen data-root.
| Relativ sökväg | Absolut sökväg |
|---|---|
| /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 |
Arbetskatalog
När du kör U-SQL-skriptet lokalt skapas en arbetskatalog under kompileringen under den aktuella katalogen som körs. Förutom kompileringsutdata kopieras de nödvändiga körningsfilerna för lokal körning till den här arbetskatalogen. Arbetskatalogens rotmapp kallas "ScopeWorkDir" och filerna under arbetskatalogen är följande:
| Katalog/fil | Katalog/fil | Katalog/fil | Definition | Description |
|---|---|---|---|---|
| C6A101DDCB470506 | Hash-sträng för körningsversion | Skuggkopia av körningsfiler som behövs för lokal körning | ||
| Script_66AE4909AA0ED06C | Skriptnamn + hashsträng för skriptsökväg | Kompileringsutdata och körningsstegsloggning | ||
| _script_.abr | Kompilatorutdata | Algebra-fil | ||
| _ScopeCodeGen_.* | Kompilatorutdata | Genererad hanterad kod | ||
| _ScopeCodeGenEngine_.* | Kompilatorutdata | Genererad intern kod | ||
| refererade sammansättningar | Sammansättningsreferens | Refererade sammansättningsfiler | ||
| deployed_resources | Resursdistribution | Resursdistributionsfiler | ||
| xxxxxxxx.xxx[1..n]_*.* | Körningslogg | Logg för körningssteg |
Använda SDK:et från kommandoraden
Hjälpprogrammets kommandoradsgränssnitt
Under SDK-katalogen\build\runtime är LocalRunHelper.exe kommandoradshjälpprogrammet som tillhandahåller gränssnitt till de flesta av de vanliga lokalkörningsfunktionerna. Både kommandot och argumentväxlarna är skiftlägeskänsliga. Så här anropar du den:
LocalRunHelper.exe <command> <Required-Command-Arguments> [Optional-Command-Arguments]
Kör LocalRunHelper.exe utan argument eller med hjälpväxlingen för att visa hjälpinformationen:
> 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
I hjälpinformationen:
- Kommandot anger kommandots namn.
- Obligatoriskt argument listar argument som måste anges.
- Valfritt argument visar argument som är valfria med standardvärden. Valfria booleska argument har inte parametrar och deras utseenden betyder negativt för deras standardvärde.
Returnera värde och loggning
Hjälpprogrammet returnerar 0 för lyckat resultat och -1 för fel. Som standard skickar hjälpkomponenten alla meddelanden till den aktuella konsolen. De flesta kommandon har dock stöd för det valfria argumentet -MessageOut path_to_log_file som omdirigerar utdata till en loggfil.
Konfigurera miljövariabel
Lokal U-SQL-körning behöver en angiven datarot som lokalt lagringskonto och en angiven CppSDK-sökväg för beroenden. Du kan båda ange argumentet i kommandoraden eller ange miljövariabeln för dem.
Ange miljövariabeln SCOPE_CPP_SDK .
Om du får Microsoft Visual C++ och Windows SDK genom att installera Data Lake Tools för Visual Studio kontrollerar du att du har följande mapp:
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\CppSDKDefiniera en ny miljövariabel med namnet SCOPE_CPP_SDK så att den pekar på den här katalogen. Eller kopiera mappen till den andra platsen och ange SCOPE_CPP_SDK .
Förutom att ange miljövariabeln kan du ange argumentet -CppSDK när du använder kommandoraden. Det här argumentet skriver över din CppSDK-standardmiljövariabel.
Ange miljövariabeln LOCALRUN_DATAROOT .
Definiera en ny miljövariabel med namnet LOCALRUN_DATAROOT som pekar på dataroten.
Förutom att ange miljövariabeln kan du ange argumentet -DataRoot med datarotsökvägen när du använder en kommandorad. Det här argumentet skriver över standardvariabeln för datarotsmiljön. Du måste lägga till det här argumentet på varje kommandorad som du kör så att du kan skriva över standardvariabeln för datarotsmiljön för alla åtgärder.
Användningsexempel för SDK-kommandorad
Kompilera och kör
Körningskommandot används för att kompilera skriptet och sedan köra kompilerade resultat. Dess kommandoradsargument är en kombination av dem från kompilera och köra.
LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]
Följande är valfria argument för körning:
| Argument | Standardvärde | Beskrivning |
|---|---|---|
| -Codebehind | Falskt | Skriptet har .cs bakom sig |
| -CppSDK | CppSDK-katalog | |
| -DataRoot | Miljövariabeln DataRoot | DataRoot för lokal körning, som standard är miljövariabeln "LOCALRUN_DATAROOT" |
| -MessageOut | Dumpa meddelanden på konsolen till en fil | |
| -Parallell | 1 | Kör planen med den angivna parallelliteten |
| -Referenser | Lista över sökvägar till extra referenssammansättningar eller datafiler med bakomliggande kod, avgränsade med ";" | |
| -UdoRedirect | Falskt | Generera omdirigeringskonfiguration för Udo-sammansättning |
| -UseDatabase | master | Databas som ska användas för kod bakom tillfällig sammansättningsregistrering |
| -Utförlig | Falskt | Visa detaljerade utdata från körning |
| -WorkDir | Aktuell katalog | Katalog för kompilatoranvändning och utdata |
| -RunScopeCEP | 0 | ScopeCEP-läge som ska användas |
| -ScopeCEPTempPath | temp | Temporär sökväg att använda för strömmande data |
| -OptFlags | Kommaavgränsad lista över optimizerflaggor |
Här är ett exempel:
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
Förutom att kombinera kompilera och köra kan du kompilera och köra de kompilerade körbara objekten separat.
Kompilera ett U-SQL-skript
Kompileringskommandot används för att kompilera ett U-SQL-skript till körbara filer.
LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]
Följande är valfria argument för kompilering:
| Argument | Description |
|---|---|
| -CodeBehind [standardvärdet 'False'] | Skriptet har .cs bakom sig |
| -CppSDK [standardvärde ''] | CppSDK-katalog |
| -DataRoot [standardvärdet "DataRoot environment variable"] | DataRoot för lokal körning, som standard är miljövariabeln "LOCALRUN_DATAROOT" |
| -MessageOut [standardvärde ''] | Dumpa meddelanden på konsolen till en fil |
| -Referenser [standardvärde ''] | Lista över sökvägar till extra referenssammansättningar eller datafiler med bakomliggande kod, avgränsade med ";" |
| -Shallow [standardvärdet 'False'] | Ytlig kompilering |
| -UdoRedirect [standardvärdet "False"] | Generera omdirigeringskonfiguration för Udo-sammansättning |
| -UseDatabase [standardvärdet "master"] | Databas som ska användas för kod bakom tillfällig sammansättningsregistrering |
| -WorkDir [standardvärdet "Current Directory"] | Katalog för kompilatoranvändning och utdata |
| -RunScopeCEP [standardvärdet '0'] | ScopeCEP-läge som ska användas |
| -ScopeCEPTempPath [standardvärdet temp] | Temporär sökväg att använda för strömmande data |
| -OptFlags [standardvärde ''] | Kommaavgränsad lista över optimizerflaggor |
Här följer några användningsexempel.
Kompilera ett U-SQL-skript:
LocalRunHelper compile -Script d:\test\test1.usql
Kompilera ett U-SQL-skript och ange datarotmappen. Detta skriver över den angivna miljövariabeln.
LocalRunHelper compile -Script d:\test\test1.usql –DataRoot c:\DataRoot
Kompilera ett U-SQL-skript och ange en arbetskatalog, referenssammansättning och databas:
LocalRunHelper compile -Script d:\test\test1.usql -WorkDir d:\test\bin -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB
Köra kompilerade resultat
Körningskommandot används för att köra kompilerade resultat.
LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]
Följande är valfria argument för körning:
| Argument | Standardvärde | Beskrivning |
|---|---|---|
| -DataRoot | '' | Datarot för metadatakörning. Standardinställningen är LOCALRUN_DATAROOT miljövariabeln. |
| -MessageOut | '' | Dumpa meddelanden i konsolen till en fil. |
| -Parallell | '1' | Indikator för att köra de genererade lokala körningsstegen med den angivna parallellitetsnivån. |
| -Utförlig | "Falskt" | Indikator för att visa detaljerade utdata från körning. |
Här är ett användningsexempel:
LocalRunHelper execute -Algebra d:\test\workdir\C6A101DDCB470506\Script_66AE4909AA0ED06C\__script__.abr –DataRoot c:\DataRoot –Parallel 5
Använda SDK med programmeringsgränssnitt
Alla programmeringsgränssnitt finns i LocalRunHelper.exe. Du kan använda dem för att integrera funktionerna i U-SQL SDK och C#-testramverket för att skala ditt lokala U-SQL-skripttest. I den här artikeln ska jag använda C#-standardenhetens testprojekt för att visa hur du använder dessa gränssnitt för att testa ditt U-SQL-skript.
Steg 1: Skapa C#-enhetstestprojekt och konfiguration
Skapa ett C#-enhetstestprojekt via File > New > Project > Visual C# > Test > Unit Test Project.
Lägg till LocalRunHelper.exe som referens för projektet. LocalRunHelper.exe finns på \build\runtime\LocalRunHelper.exe i NuGet-paketet.
U-SQL SDK stöder endast x64-miljö, se till att ange byggplattformsmålet som x64. Du kan ange det via Project Property > Build > Platform-målet.
Se till att ange testmiljön som x64. I Visual Studio kan du ange den via Test > testinställningar > Standardprocessorarkitektur > x64.
Se till att kopiera alla beroendefiler under NugetPackage\build\runtime\ till projektarbetskatalogen, som vanligtvis finns under ProjectFolder\bin\x64\Debug.
Steg 2: Skapa U-SQL-skripttestfall
Nedan visas exempelkoden för U-SQL-skripttest. För testning måste du förbereda skript, indatafiler och förväntade utdatafiler.
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);
}
}
}
Programmeringsgränssnitt i LocalRunHelper.exe
LocalRunHelper.exe tillhandahåller programmeringsgränssnitten för lokal U-SQL-kompilering, körning osv. Gränssnitten visas på följande sätt.
Konstruktor
public LocalRunHelper([System.IO.TextWriter messageOutput = null])
| Parameter | Typ | Description |
|---|---|---|
| messageOutput | System.IO.TextWriter | för utdatameddelanden ställer du in på null för att använda konsolen |
Egenskaper
| Egenskap | Typ | Description |
|---|---|---|
| AlgebraPath | sträng | Sökvägen till algebrafilen (algebrafilen är ett av kompileringsresultaten) |
| CodeBehindReferences | sträng | Om skriptet har annan kod bakom referenser anger du sökvägarna avgränsade med ";" |
| CppSdkDir | sträng | CppSDK-katalog |
| CurrentDir | sträng | Aktuell katalog |
| DataRoot | sträng | Datarotsökväg |
| DebuggerMailPath | sträng | Sökvägen till felsökaren mailslot |
| GenerateUdoRedirect | boolesk | Om vi vill generera konfigurationen för omdirigering av sammansättningsinläsning åsidosättning |
| HasCodeBehind | boolesk | Om skriptet har bakomliggande kod |
| InputDir | sträng | Katalog för indata |
| MessagePath | sträng | Sökväg till meddelandedumpfil |
| OutputDir | sträng | Katalog för utdata |
| Parallellitet | int | Parallellitet för att köra algebran |
| ParentPid | int | PID för den överordnade som tjänsten övervakar att avsluta, inställd på 0 eller negativ att ignorera |
| Resultpath | sträng | Sökväg till resultatdumpfil |
| RuntimeDir | sträng | Körningskatalog |
| ScriptPath | sträng | Var du hittar skriptet |
| Grunt | boolesk | Ytlig kompilering eller inte |
| TempDir | sträng | Temp-katalog |
| UseDataBase | sträng | Ange den databas som ska användas för kod bakom tillfällig sammansättningsregistrering, huvudserver som standard |
| WorkDir | sträng | Önskad arbetskatalog |
Metod
| Metod | Beskrivning | Returnera | Parameter |
|---|---|---|---|
| public bool DoCompile() | Kompilera U-SQL-skriptet | Sant om framgång | |
| public bool DoExec() | Kör det kompilerade resultatet | Sant om framgång | |
| public bool DoRun() | Kör U-SQL-skriptet (Kompilera + kör) | Sant om framgång | |
| public bool IsValidRuntimeDir(strängsökväg) | Kontrollera om den angivna sökvägen är giltig körningssökväg | Sant för giltigt | Sökvägen till körningskatalogen |
Vanliga frågor och svar om vanliga problem
Fel 1
E_CSC_SYSTEM_INTERNAL: Internt fel! Det gick inte att läsa in filen eller sammansättningen "ScopeEngineManaged.dll" eller något av dess beroenden. Det gick inte att hitta den angivna modulen.
Kontrollera följande:
- Kontrollera att du har x64-miljön. Byggmålplattformen och testmiljön ska vara x64, se Steg 1: Skapa C#-enhetstestprojekt och konfiguration ovan.
- Kontrollera att du har kopierat alla beroendefiler under NugetPackage\build\runtime\ till projektarbetskatalogen.
Nästa steg
- Information om U-SQL finns i Kom igång med U-SQL-språk i Azure Data Lake Analytics.
- Information om att logga diagnostik finns i Komma åt diagnostikloggar för Azure Data Lake Analytics.
- En mer komplex fråga finns i Analysera webbplatsloggar med Hjälp av Azure Data Lake Analytics.
- Information om jobb finns i Använda jobbwebbläsaren och jobbvyn för Azure Data Lake Analytics-jobb.
- Information om hur du använder körningsvyn för hörn finns i Använda hörnkörningsvyn i Data Lake Tools för Visual Studio.