Executar e testar U-SQL com o SDK do U-SQL do Azure Data Lake

Importante

O Azure Data Lake Analytics desativado em 29 de fevereiro de 2024. Saiba mais nesse comunicado.

Para análise de dados, sua organização pode usar o Azure Synapse Analytics ou o Microsoft Fabric.

Ao desenvolver o script U-SQL, é comum executar e testar o script U-SQL localmente antes de enviá-lo para a nuvem. O Azure Data Lake fornece um pacote NuGet chamado SDK do U-SQL do Azure Data Lake para esse cenário, por meio do qual você pode dimensionar facilmente a execução e o teste do U-SQL. Também é possível integrar esse teste do U-SQL ao sistema de CI (Integração Contínua) para automatizar a compilação e o teste.

Se você se preocupa em como executar e depurar o script U-SQL no local manualmente com ferramentas de GUI, é possível usar as Ferramentas do Azure Data Lake para Visual Studio para essa finalidade. Saiba mais aqui.

Instalar o SDK do U-SQL do Azure Data Lake

Você pode obter o SDK do U-SQL do Azure Data Lake aqui em NuGet.org. Antes de usá-lo, você precisa verificar se tem dependências da maneira a seguir.

Dependências

O SDK para U-SQL do Data Lake exige as seguintes dependências:

  • Microsoft .NET Framework 4.6 ou mais recente.

  • Microsoft Visual C++ 14 e SDK do Windows 10.0.10240.0 ou mais novo (que é chamado CppSDK neste artigo). Há duas maneiras de obter o CppSDK:

    • Instalar o Visual Studio Community Edition. Você terá uma pasta \Windows Kits\10 na pasta Arquivos de Programa – por exemplo, C:\Program Files (x86) \Windows Kits\10. Você também encontrará a versão do SDK do Windows 10 em \Windows Kits\10\Lib. Se você não vir essas pastas, reinstale o Visual Studio e selecione o SDK do Windows 10 durante a instalação. Se você tiver isso instalado com o Visual Studio, o compilador local do U-SQL o encontrará automaticamente.

      SDK para Windows 10 da execução local das Ferramentas do Data Lake para Visual Studio

    • Instalar Ferramentas do Data Lake para Visual Studio. Você pode encontrar os arquivos predefinidos do SDK do Windows e do Visual C++ em C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.

      Nesse caso, o compilador local do U-SQL não consegue localizar as dependências automaticamente. Você precisa especificar o caminho CppSDK para ele. Você pode copiar os arquivos para outro local ou usá-los como estão.

Entender os conceitos básicos

Raiz de dados

A pasta raiz de dados é um "repositório local" para a conta de computador local. Ela equivale à conta do Azure Data Lake Store de uma conta do Data Lake Analytics. Alternar para uma pasta raiz de dados diferente é como alternar para uma conta de repositório diferente. Se você quiser acessar dados compartilhados normalmente com pastas raiz de dados diferentes, deverá usar caminhos absolutos em seus scripts. Ou criar links simbólicos de sistema de arquivo (por exemplo, mklink em NTFS) na pasta raiz de dados para apontar para os dados compartilhados.

A pasta raiz de dados é usada para:

  • Armazenar metadados locais, incluindo bancos de dados, tabelas, TVFs (funções com valor de tabela) e assemblies.
  • Pesquisar os caminhos de entrada e saída que são definidos como caminhos relativos no U-SQL. Usar caminhos relativos facilita a implantação dos projetos U-SQL no Azure.

Caminho de arquivo no U-SQL

Você pode usar um caminho relativo e um caminho absoluto local em scripts U-SQL. O caminho relativo é relativo ao caminho da pasta raiz de dados especificado. Recomendamos que você use "/" como o separador de caminho para tornar seus scripts compatíveis com o lado do servidor. A seguir, alguns exemplos de caminhos relativos e os respectivos caminhos absolutos equivalentes. Nesses exemplos, C:\LocalRunDataRoot é a pasta raiz de dados.

Caminho relativo Caminho absoluto
/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

Diretório de trabalho

Ao executar o script U-SQL localmente, um diretório de trabalho é criado durante a compilação no diretório de execução atual. Além das saídas de compilação, os arquivos de runtime necessários para execução local são copiados em sombra para esse diretório de trabalho. A pasta raiz do diretório de trabalho é chamada “ScopeWorkDir” e os arquivos no diretório de trabalho são os seguintes:

Diretório/arquivo Diretório/arquivo Diretório/arquivo Definição Descrição
C6A101DDCB470506 Cadeia de caracteres de hash da versão do runtime Cópia de sombra dos arquivos de runtime necessários para execução local
Script_66AE4909AA0ED06C Nome do script + cadeia de caracteres de hash do caminho do script Saídas da compilação e log das etapas de execução
_script_.abr Saída do compilador Arquivo de álgebra
_ScopeCodeGen_.* Saída do compilador Código gerenciado gerado
_ScopeCodeGenEngine_.* Saída do compilador Código nativo gerado
assemblies referenciados Referência de assembly Arquivos de assembly referenciado
deployed_resources Implantação de recursos Arquivos da implantação de recursos
xxxxxxxx.xxx[1..n]_*.* Log de execução Log das etapas de execução

Usar o SDK da linha de comando

Interface de linha de comando do aplicativo auxiliar

Em directory\build\runtime do SDK, LocalRunHelper.exe é o aplicativo auxiliar de linha de comando que fornece interfaces para a maioria das funções de execução local frequentemente usadas. As opções de comando e argumento diferenciam maiúsculas de minúsculas. Para invocá-lo:

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

Execute LocalRunHelper.exe sem argumentos ou com a opção help para mostrar as informações de ajuda:

> 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

Nas informações de ajuda:

  • Command fornece o nome do comando.
  • Required Argument lista argumentos que devem ser fornecidos.
  • Optional Argument lista argumentos que são opcionais e com valores padrão. Os argumentos boolianos opcionais não têm parâmetros e as respectivas aparências são negativas para o respectivo valor padrão.

Valor de retorno e registro em log

O aplicativo auxiliar retorna 0 em caso de sucesso e -1 em caso de falha. Por padrão, o auxiliar enviará todas as mensagens para o console atual. No entanto, a maioria dos comandos dá suporte ao argumento opcional -MessageOut path_to_log_file, que redireciona as saídas para um arquivo de log.

Configurando variáveis de ambiente

A execução local do U-SQL precisa de uma raiz de dados especificada como conta de armazenamento local e um caminho CppSDK especificado para dependências. É possível definir o argumento na linha de comando ou definir a variável de ambiente para elas.

  • Defina a variável de ambiente SCOPE_CPP_SDK.

    Se obtiver o SDK do Windows e Microsoft Visual C++ instalando as Ferramentas do Data Lake para Visual Studio, verifique se você tem a seguinte pasta:

    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 uma nova variável de ambiente chamada SCOPE_CPP_SDK para pontar para esse diretório. Ou copie a pasta para outro local e especifique SCOPE_CPP_SDK dessa forma.

    Além de definir a variável de ambiente, você também pode especificar o argumento -CppSDK ao usar a linha de comando. Esse argumento substitui a variável de ambiente CppSDK padrão.

  • Defina a variável de ambiente LOCALRUN_DATAROOT.

    Defina uma nova variável de ambiente chamada LOCALRUN_DATAROOT que aponta para a raiz de dados.

    Além de definir a variável de ambiente, você pode especificar o argumento -DataRoot com o caminho raiz de dados ao usar a linha de comando. Esse argumento substitui a variável de ambiente de raiz de dados padrão. Você precisa adicionar esse argumento para cada linha de comando em execução para que você possa substituir a variável de ambiente de raiz de dados padrão em todas as operações.

Amostras de uso da linha de comando do SDK

Compilar e executar

O comando run é usado para compilar o script e executar resultados compilados. Seus argumentos de linha de comando são uma combinação dos argumentos de compile e execute.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

Estes são os argumentos opcionais para run:

Argumento Valor padrão Descrição
-CodeBehind Falso O script tem o code-behind .cs
-CppSDK Diretório do CppSDK
-DataRoot Variável de ambiente DataRoot DataRoot para execução local, padrão para a variável de ambiente “LOCALRUN_DATAROOT”
-MessageOut Mensagens de despejo no console para um arquivo
-Parallel 1 Executar o plano com o paralelismo especificado
-References Lista de caminhos para os assemblies de referência extra ou arquivos de dados do code-behind, separados por ';'
-UdoRedirect Falso Gerar configuração de redirecionamento de assembly UDO
-UseDatabase master Banco de dados a ser usado para registro do assembly temporário do code-behind
-Verbose Falso Mostrar saídas detalhadas do runtime
-WorkDir Diretório atual Diretório para uso do compilador e saídas
-RunScopeCEP 0 Modo ScopeCEP a ser usado
-ScopeCEPTempPath temp Caminho temporário a ser usado para transmissão de dados
-OptFlags Lista separada por vírgula de sinalizadores do otimizador

Veja um exemplo:

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

Além de combinar compile e execute, é possível compilar e executar os executáveis compilados separadamente.

Compilar um script U-SQL

O comando compile é usado para compilar um script U-SQL para executáveis.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Estes são os argumentos opcionais para compile:

Argumento Descrição
-CodeBehind [valor padrão 'False'] O script tem o code-behind .cs
-CppSDK [valor padrão ''] Diretório do CppSDK
-DataRoot [valor padrão “variável de ambiente DataRoot”] DataRoot para execução local, padrão para a variável de ambiente “LOCALRUN_DATAROOT”
-MessageOut [valor padrão ''] Mensagens de despejo no console para um arquivo
-References [valor padrão ''] Lista de caminhos para os assemblies de referência extra ou arquivos de dados do code-behind, separados por ';'
-Shallow [valor padrão 'False'] Compilação superficial
-UdoRedirect [valor padrão 'False'] Gerar configuração de redirecionamento de assembly UDO
-UseDatabase [valor padrão 'master'] Banco de dados a ser usado para registro do assembly temporário do code-behind
-WorkDir [valor padrão “Diretório Atual”] Diretório para uso do compilador e saídas
-RunScopeCEP [valor padrão “0”] Modo ScopeCEP a ser usado
-ScopeCEPTempPath [valor padrão “temp”] Caminho temporário a ser usado para transmissão de dados
-OptFlags [valor padrão ''] Lista separada por vírgula de sinalizadores do otimizador

Veja alguns exemplos de uso.

Compilar um script U-SQL:

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

Compilar um script U-SQL e definir a pasta raiz de dados. Isso substituirá a variável de ambiente set.

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

Compilar um script U-SQL e definir um diretório de trabalho, o assembly de referência e o banco de dados:

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

Executar resultados compilados

O comando execute é usado para executar os resultados compilados.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Estes são os argumentos opcionais para execute:

Argumento Valor padrão Descrição
-DataRoot '' Raiz de dados para a execução de metadados. A variável de ambiente LOCALRUN_DATAROOT passa a ser o padrão.
-MessageOut '' Despeje as mensagens do console em um arquivo.
-Parallel '1' Indicador para executar as etapas de execução local geradas com o nível de paralelismo especificado.
-Verbose 'False' Indicador para mostrar saídas detalhadas do runtime.

Aqui está um exemplo de uso:

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

Usar o SDK com interfaces de programação

As interfaces de programação estão localizadas no LocalRunHelper.exe. Você pode usá-los para integrar a funcionalidade do SDK para U-SQL e a estrutura de teste C# a fim de dimensionar o teste local do script U-SQL. Neste artigo, usarei o projeto de teste de unidade C# padrão para mostrar como usar essas interfaces para testar o script U-SQL.

Etapa 1: Criar o projeto de teste de unidade do C# e a configuração

  • Crie um projeto de teste de unidade do C# por meio de Arquivo > Novo > Projeto > Visual C# > Teste > Projeto de Teste de Unidade.

  • Adicione LocalRunHelper.exe como uma referência do projeto. O LocalRunHelper.exe está localizado em \build\runtime\LocalRunHelper.exe no pacote NuGet.

    SDK do U-SQL do Azure Data Lake – Adicionar referência

  • O SDK do U-SQL dá suporte apenas ao ambiente x64, certifique-se de definir o destino da plataforma de build como x64. É possível definir isso por meio de Propriedade do Projeto > Build > Destino da plataforma.

    SDK do U-SQL do Azure Data Lake – Configurar projeto do x64

  • Lembre-se de definir o ambiente de teste como x64. No Visual Studio, é possível defini-lo por meio de Teste > Configurações do Teste > Arquitetura do Processador Padrão > x64.

    SDK do U-SQL do Azure Data Lake – Configurar ambiente de teste x64

  • Copie todos os arquivos de dependência em NugetPackage\build\runtime\ para o diretório de trabalho do projeto, que geralmente está em ProjectFolder\bin\x64\Debug.

Etapa 2: Criar um caso de teste do script U-SQL

Veja abaixo o código de exemplo para o teste de script U-SQL. Para testar, você precisa preparar scripts, arquivos de entrada e os arquivos de saída 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 programação em LocalRunHelper.exe

O LocalRunHelper.exe fornece as interfaces de programação para compilação local do U-SQL, execução etc. As interfaces são listadas como abaixo.

Construtor

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

Parâmetro Tipo Descrição
messageOutput System.IO.TextWriter para mensagens de saída, definido como nulo para usar o Console

Propriedades

Propriedade Tipo Descrição
AlgebraPath string O caminho para o arquivo de álgebra (o arquivo de álgebra é um dos resultados da compilação)
CodeBehindReferences string Se o script tiver outras referências de código por trás, especifique os caminhos separados com ';'
CppSdkDir string Diretório do CppSDK
CurrentDir string Diretório atual
DataRoot string Caminho da raiz de dados
DebuggerMailPath string O caminho para o slot de correio do depurador
GenerateUdoRedirect bool Se quisermos gerar a configuração de substituição do redirecionamento de carregamento do assembly
HasCodeBehind bool Se o script tiver code-behind
InputDir string Diretório dos dados de entrada
MessagePath string Caminho do arquivo de despejo da mensagem
OutputDir string Diretório dos dados de saída
Paralelismo INT Paralelismo para executar a álgebra
ParentPid INT PID do pai no qual o serviço monitora a saída, definido como 0 ou negativo para ignorar
ResultPath string Caminho do arquivo de despejo do resultado
RuntimeDir string Diretório do runtime
ScriptPath string Local em que o script pode ser encontrado
Shallow bool Compilação superficial ou não
TempDir string Diretório temporário
UseDataBase string Especifique o banco de dados a ser usado para o registro de assembly temporário code-behind, mestre por padrão
WorkDir string Diretório de trabalho preferencial

Método

Método Descrição Retorno Parâmetro
public bool DoCompile() Compilar o script U-SQL Verdadeiro se tiver êxito
public bool DoExec() Executar o resultado compilado Verdadeiro se tiver êxito
public bool DoRun() Executar o script U-SQL (Compilar + Executar) Verdadeiro se tiver êxito
public bool IsValidRuntimeDir(string path) Verificar se o caminho fornecido é um caminho de runtime válido Verdadeiro para válido O caminho do diretório de runtime

Perguntas frequentes sobre um problema comum

Erro 1

E_CSC_SYSTEM_INTERNAL: Erro interno. Não foi possível carregar o arquivo ou o assembly “ScopeEngineManaged.dll” ou uma de suas dependências. O módulo especificado não pôde ser encontrado.

Verifique o seguinte:

  • Verifique se você tem o ambiente x64. A plataforma de destino do build e o ambiente de teste devem ser x64; consulte Etapa 1: Criar configuração e projeto de teste de unidade do C# acima.
  • Verifique se você copiou todos os arquivos de dependência em NugetPackage\build\runtime\ para o diretório de trabalho do projeto.

Próximas etapas