Compartir a través de


Ejecución y prueba de U-SQL con el SDK de U-SQL para Azure Data Lake

Importante

Azure Data Lake Analytics retiró el 29 de febrero de 2024. Más información sobre este anuncio.

Para el análisis de datos, su organización puede usar Azure Synapse Analytics o Microsoft Fabric.

Al desarrollar un script U-SQL, es habitual ejecutar y probar el script U-SQL localmente antes de enviarlo a la nube. Azure Data Lake proporciona un paquete NuGet denominado SDK de U-SQL de Azure Data Lake para este escenario, a través del cual puede escalar y probar fácilmente U-SQL. También es posible integrar esta prueba de U-SQL con ci (integración continua) para automatizar la compilación y la prueba.

Si está interesado en cómo ejecutar y depurar localmente y de forma manual el script U-SQL con las herramientas GUI, entonces puede usar las Herramientas de Azure Data Lake para Visual Studio. Puede obtener más información sobre esto aquí.

Instalación del SDK de U-SQL para Azure Data Lake

Puede obtener el SDK de U-SQL para Azure Data Lake aquí en Nuget.org. Y, antes de usarlo, debe asegurarse de que dispone de las siguientes dependencias.

Dependencias

El SDK de U-SQL para Data Lake requiere las siguientes dependencias:

  • Microsoft .NET Framework 4.6 o superior.

  • Microsoft Visual C++ 14 y el SDK de Windows 10.0.10240.0 o posterior (que se denomina CppSDK en este artículo). Existen dos formas de obtener CppSDK:

    • Instale Visual Studio Community Edition. Debe tener una carpeta "\Windows Kits\10" en "Archivos de programa", por ejemplo, "C:\Archivos de programa (x86)\Windows Kits\10\". También encontrará la versión del SDK de Windows 10 en \Windows Kits\10\Lib. Si no ve estas carpetas, vuelva a instalar Visual Studio y asegúrese de seleccionar el SDK de Windows 10 durante la instalación. Si ya lo tiene instalado con Visual Studio, el compilador local de U-SQL lo encontrará automáticamente.

      SDK de Windows 10 para ejecución local de Data Lake Tools para Visual Studio

    • Instale Data Lake Tools para Visual Studio. Puede encontrar los archivos de Visual C++ y Windows SDK preempaquetados en C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK..

      En este caso, el compilador local de U-SQL no puede encontrar automáticamente las dependencias. Debe especificar la ruta de acceso de CppSDK para él. Puede copiar los archivos en otra ubicación o simplemente usarla como está.

Conceptos básicos

Raíz de datos

La carpeta raíz de datos es un "almacén local" de la cuenta de proceso local. Es equivalente a la cuenta de Azure Data Lake Store de una cuenta de Data Lake Analytics. Cambiar a una carpeta raíz de datos diferente es como que cambiar a otra cuenta de almacén. Si desea tener acceso a datos compartidos normalmente con carpetas raíz de datos diferentes, debe usar rutas de acceso absolutas en los scripts. O bien, cree vínculos simbólicos del sistema de archivos (por ejemplo, mklink en NTFS) en la carpeta raíz de datos para que apunte a los datos compartidos.

La carpeta raíz de datos se utiliza para:

  • Almacenar metadatos, lo que incluye bases de datos, tablas, funciones con valores de tabla (TVF) y ensamblados.
  • Buscar las rutas de acceso de entrada y salida que se definen como rutas de acceso relativas en U-SQL. El uso de rutas de acceso relativas facilita la implementación de sus proyectos U-SQL en Azure.

Ruta de archivo de U-SQL

Puede usar tanto una ruta de acceso relativa como una ruta de acceso absoluta local en los scripts U-SQL. La ruta de acceso relativa es relativa a la ruta de acceso de la carpeta raíz de datos especificada. Se recomienda usar "/" como separador de ruta de acceso para que los scripts sean compatibles con el lado servidor. Estos son algunos ejemplos de rutas de acceso relativas y sus rutas de acceso absolutas equivalentes. En estos ejemplos, C:\LocalRunDataRoot es la carpeta raíz de datos.

Ruta de acceso relativa Ruta de acceso absoluta
/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

Directorio de trabajo

Al ejecutar localmente el script U-SQL, se crea un directorio de trabajo durante la compilación en el directorio que se está ejecutando actualmente. Además de las salidas de compilación, se creará una instantánea de los archivos del runtime necesarios para la ejecución local en este directorio de trabajo. La carpeta de raíz del directorio de trabajo se denomina "ScopeWorkDir" y los archivos dentro el directorio de trabajo son los siguientes:

Directorio o archivo Directorio o archivo Directorio o archivo Definición Descripción
C6A101DDCB470506 Cadena de hash de la versión del runtime Instantánea de los archivos del runtime necesarios para la ejecución local
Script_66AE4909AA0ED06C Nombre de script + cadena de hash de la ruta de acceso del script Resultados de compilación y registro de los pasos de ejecución
_script_.abr Salida del compilador Archivo de álgebra
_ScopeCodeGen_.* Salida del compilador Código administrado generado
_ScopeCodeGenEngine_.* Salida del compilador Código nativo generado
ensamblados de referencia Referencia de ensamblado Archivos de ensamblados de referencia
deployed_resources Implementación de recursos Archivos de implementación de recursos
xxxxxxxx.xxx[1..n]_*.* Registro de ejecución Registro de pasos de ejecución

Uso del SDK desde la línea de comandos

Interfaz de la línea de comandos del asistente

El archivo LocalRunHelper.exe se encuentra en el directorio del SDK, en build/runtime, y es el asistente de línea de comandos que proporciona interfaces a la mayoría de las funciones de ejecución local de uso frecuente. Tanto el comando como los modificadores de argumento distinguen mayúsculas de minúsculas. Para invocarla:

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

Ejecute LocalRunHelper.exe sin argumentos o con el modificador help para mostrar la información de ayuda:

> 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

En la información de ayuda:

  • Command proporciona el nombre del comando.
  • Required Argument enumera los argumentos que se deben proporcionar.
  • Optional Argument enumera argumentos que son opcionales, con los valores predeterminados. Los argumentos opcionales booleanos no tienen parámetros y sus repeticiones implican un valor negativo de sus valores predeterminados.

Valor devuelto y registro

El asistente devuelve 0 si se ha realizado correctamente y -1 en caso contrario. De forma predeterminada, el asistente envía todos los mensajes a la consola actual. Sin embargo, la mayoría de los comandos admiten el argumento opcional -MessageOut ruta_de_acceso_al_archivo_de_registro que redirige las salidas a un archivo de registro.

Configuración de la variable de entorno

La ejecución local de U-SQL necesita una raíz de datos especificada como cuenta de almacenamiento local y una ruta de acceso de CppSDK especificada para las dependencias. Puede establecer el argumento en la línea de comandos o bien puede establecer la variable de entorno para ellos.

  • Establezca la variable de entorno SCOPE_CPP_SDK.

    Si obtiene Microsoft Visual C++ y Windows SDK con la instalación de Data Lake Tools para Visual Studio, compruebe que dispone de la siguiente carpeta:

    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

    Defina una nueva variable de entorno denominada SCOPE_CPP_SDK para que apunte a este directorio. O copie la carpeta en otra ubicación y especifique SCOPE_CPP_SDK como eso.

    Además de establecer la variable de entorno, también puede especificar el argumento -CppSDK cuando se utiliza la línea de comandos. Este argumento sobrescribe la variable de entorno CppSDK predeterminada.

  • Establezca la variable de entorno LOCALRUN_DATAROOT.

    Defina una nueva variable de entorno denominada LOCALRUN_DATAROOT que apunte a la raíz de datos.

    Además de establecer la variable de entorno, puede especificar el argumento -DataRoot con la ruta de acceso raíz de datos cuando se utiliza la línea de comandos. Este argumento sobrescribe la variable de entorno raíz de datos predeterminada. Necesita agregar este argumento a cada línea de comandos que esté ejecutando para que pueda sobrescribir la variable de entorno raíz de datos predeterminada para todas las operaciones.

Ejemplos de uso de línea de comandos del SDK

Compilación y ejecución

El comando run se utiliza para compilar el script y ejecutar después los resultados compilados. Sus argumentos de línea de comandos son una combinación de los de compile y execute.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

A continuación se muestran los argumentos opcionales para run:

Argumento Valor predeterminado Descripción
-CodeBehind False El script tiene código subyacente .cs
-CppSDK Directorio CppSDK
-DataRoot Variable de entorno de DataRoot DataRoot para ejecución local; el valor predeterminado es la variable de entorno 'LOCALRUN_DATAROOT'
-MessageOut Volcar mensajes de la consola en un archivo
-Parallel 1 Ejecutar el plan con el paralelismo especificado
-References Lista de rutas de acceso a los ensamblados de referencia adicionales o archivos de datos de código subyacente, separadas por ';'
-UdoRedirect False Generar la configuración de redirección de ensamblado de Udo
-UseDatabase maestro Base de datos que se utilizará para el registro de ensamblados temporal de código subyacente
-Verbose False Mostrar resultados detallados del runtime
-WorkDir Directorio actual Directorio para las salidas y el uso del compilador
-RunScopeCEP 0 Modo de ScopeCEP que se utilizará
-ScopeCEPTempPath temp Ruta de acceso temporal que se usará para el streaming de datos
-OptFlags Lista de marcas de optimizador separadas por comas

Este es un ejemplo:

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

Además de combinar compile y execute, puede compilar y ejecutar los ejecutables compilados por separado.

Compilación de un script U-SQL

El comando compile se utiliza para compilar un script U-SQL en los archivos ejecutables.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

A continuación, se muestran los argumentos opcionales para compile:

Argumento Descripción
-CodeBehind [valor predeterminado 'False'] El script tiene código subyacente .cs
-CppSDK [valor predeterminado ''] Directorio CppSDK
-DataRoot [valor predeterminado 'DataRoot environment variable'] DataRoot para ejecución local; el valor predeterminado es la variable de entorno 'LOCALRUN_DATAROOT'
-MessageOut [valor predeterminado ''] Volcar mensajes de la consola en un archivo
-References [valor predeterminado ''] Lista de rutas de acceso a los ensamblados de referencia adicionales o archivos de datos de código subyacente, separadas por ';'
-Shallow [valor predeterminado 'False'] Compilación superficial
-UdoRedirect [valor predeterminado 'False'] Generar la configuración de redirección de ensamblado de Udo
-UseDatabase [valor predeterminado 'master'] Base de datos que se utilizará para el registro de ensamblados temporal de código subyacente
-WorkDir [valor predeterminado 'Current Directory'] Directorio para las salidas y el uso del compilador
-RunScopeCEP [valor predeterminado '0'] Modo de ScopeCEP que se utilizará
-ScopeCEPTempPath [valor predeterminado 'temp'] Ruta de acceso temporal que se usará para el streaming de datos
-OptFlags [valor predeterminado ''] Lista de marcas de optimizador separadas por comas

Estos son algunos ejemplos de uso.

Compile un script U-SQL:

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

Compile un script U-SQL y establezca la carpeta raíz de datos. Esto sobrescribirá la variable de entorno set.

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

Compile un script U-SQL y establezca el directorio de trabajo, el ensamblado de referencia y la base de datos:

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

Ejecución de resultados compilados

El comando execute se usa para ejecutar resultados compilados.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

A continuación, se muestran los argumentos opcionales para execute:

Argumento Valor predeterminado Descripción
-DataRoot '' Raíz de datos para la ejecución de metadatos. De manera predeterminada, es la variable de entorno LOCALRUN_DATAROOT.
-MessageOut '' Volcar mensajes de la consola en un archivo.
-Parallel '1' Indicador para ejecutar los pasos de ejecución local generados con el nivel de paralelismo especificado.
-Verbose 'False' Indicador para mostrar las salidas detalladas del tiempo de ejecución.

Presentamos un ejemplo de uso:

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

Uso del SDK con las interfaces de programación

Las interfaces de programación se encuentran en LocalRunHelper.exe. Puede utilizarlas para integrar la funcionalidad del SDK de U-SQL y la plataforma de pruebas de C# para escalar la prueba local del script U-SQL. En este artículo, usaré el proyecto de prueba unitaria estándar de C# para mostrar cómo usar estas interfaces para probar el script U-SQL.

Paso 1: crear la configuración y el proyecto de prueba unitaria de C#

  • Cree un proyecto de prueba unitaria de C# en Archivo > Nuevo > Proyecto > Visual C# > Probar > Proyecto de prueba unitaria.

  • Agregue LocalRunHelper.exe como referencia para el proyecto. El LocalRunHelper.exe se encuentra en \build\runtime\LocalRunHelper.exe en el paquete NuGet.

    Agregar referencia del SDK de U-SQL para Azure Data Lake

  • El SDK de U-SQL solo admite el entorno x64, asegúrese de establecer el destino de la plataforma de compilación como x64. Puede hacerlo mediante Propiedad del proyecto > Compilar > Destino de la plataforma.

    Configurar proyecto x64 del SDK de U-SQL para Azure Data Lake

  • Asegúrese de establecer el entorno de prueba en x64. En Visual Studio, puede hacerlo mediante Probar > Configuración de pruebas > Arquitectura del procesador predeterminada > x64.

    Configurar el entorno de prueba x64 del SDK de U-SQL para Azure Data Lake

  • Asegúrese de copiar todos los archivos de dependencia en NugetPackage\build\runtime\ en el directorio de trabajo del proyecto, que normalmente se encuentra en ProjectFolder\bin\x64\Debug.

Paso 2: crear un caso de prueba del script U-SQL

A continuación, se muestra el ejemplo de código para la prueba del script U-SQL. Para las pruebas, debe preparar los scripts, los archivos de entrada y los archivos de resultados esperados.

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

Interfaces de programación de LocalRunHelper.exe

LocalRunHelper.exe proporciona las interfaces de programación de compilación local ejecución, etc. de U-SQL. A continuación, se enumeran las interfaces.

Constructor

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

Parámetro Tipo Descripción
messageOutput System.IO.TextWriter para los mensajes de salida; establézcalo en null para usar la consola

Propiedades

Propiedad Tipo Descripción
AlgebraPath string La ruta de acceso al archivo álgebra (el archivo álgebra es uno de los resultados de compilación)
CodeBehindReferences string Si el script tiene otras referencias de código subyacente, especifique las rutas de acceso separadas por ';'
CppSdkDir string Directorio CppSDK
CurrentDir string Directorio actual
DataRoot string Ruta de acceso raíz de datos
DebuggerMailPath string La ruta de acceso al buzón interproceso del depurador
GenerateUdoRedirect bool Si desea generar carga la configuración de invalidación de redirección de carga de ensamblados
HasCodeBehind bool Si el script tiene código subyacente
InputDir string Directorio de datos de entrada
MessagePath string Ruta de acceso del archivo de volcado de memoria de mensajes
OutputDir string Directorio de datos de salida
Paralelismo int Paralelismo para ejecutar el álgebra
ParentPid int PID del elemento primario en el que se supervisa el servicio; para salir se establece en 0 o en un valor negativo para omitirlo.
ResultPath string Ruta de acceso del archivo de volcado de memoria de resultados
RuntimeDir string Directorio del entorno en tiempo de ejecución
scriptPath string Lugar donde se puede encontrar el script
Shallow bool Compilación superficial o no
TempDir string Directorio temporal
UseDataBase string Especifique la base de datos que se utilizará para el registro de ensamblados temporal de código subyacente; la maestra de forma predeterminada.
WorkDir string Directorio de trabajo preferido

Método

Método Descripción Valor devuelto Parámetro
public bool DoCompile() Compilación del script U-SQL Si se realiza correctamente, devuelve True.
public bool DoExec() Ejecución del resultado compilado Si se realiza correctamente, devuelve True.
public bool DoRun() Ejecución del script U-SQL (compilación + ejecución) Si se realiza correctamente, devuelve True.
public bool IsValidRuntimeDir(string path) Comprobación de si la ruta de acceso especificada es la ruta de acceso válida al entorno en tiempo de ejecución True para válida La ruta de acceso del directorio del entorno en tiempo de ejecución

Preguntas más frecuentes sobre problemas comunes

Error 1

E_CSC_SYSTEM_INTERNAL: Error interno. No se pudo cargar el archivo o ensamblado 'ScopeEngineManaged.dll' ni una de sus dependencias. No se pudo encontrar el módulo especificado.

Compruebe lo siguiente:

  • Asegúrese de que tiene un entorno x64. La plataforma de destino de compilación y el entorno de prueba deben ser x64. Consulte el Paso 1: crear la configuración y el proyecto de prueba unitaria de C# más arriba.
  • Asegúrese de que ha copiado todos los archivos de dependencias del directorio \build\runtime\ del paquete Nuget al directorio de trabajo del proyecto.

Pasos siguientes