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

Ao desenvolver um 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 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 manualmente o script U-SQL com ferramentas de GUI, poderá usar as Ferramentas do Azure Data Lake para Visual Studio para isso. Você pode saber mais daqui.

Instalar o SDK do U-SQL do Azure Data Lake

Você pode obter o SDK do U-SQL do Azure Data Lake aqui no Nuget.org. E antes de usá-lo, você precisa ter certeza de que tem dependências da seguinte maneira.

Dependências

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

• Microsoft .NET Framework 4.6 ou mais recente.

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

  • Instale o Visual Studio Community Edition. Você terá uma pasta \Windows Kits\10 na pasta Arquivos de Programas, por exemplo, C:\Arquivos de Programas (x86)\Kits do Windows\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.

    

  • Instale as Ferramentas do Data Lake para Visual Studio. Você pode encontrar os arquivos pré-empacotados do Visual C++ e do SDK do Windows 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 pode encontrar as dependências automaticamente. Você precisa especificar o caminho do CppSDK para ele. Você pode copiar os arquivos para outro local ou usá-los como estão.

Entender conceitos básicos

Raiz de dados

A pasta raiz de dados é um "repositório local" para a conta de computação local. É equivalente à 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 comumente compartilhados com pastas raiz de dados diferentes, deverá usar caminhos absolutos em seus scripts. Ou crie links simbólicos do sistema de arquivos (por exemplo, mklink no NTFS) na pasta raiz de dados para apontar para os dados compartilhados.

A pasta raiz de dados é usada para:

• Armazene metadados locais, incluindo bancos de dados, tabelas, TVFs (funções com valor de tabela) e assemblies.
• Procure os caminhos de entrada e saída definidos como caminhos relativos no U-SQL. O uso de caminhos relativos facilita a implantação de seus projetos U-SQL no Azure.

Caminho do 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 separador de caminho para tornar seus scripts compatíveis com o lado do servidor. Aqui estão alguns exemplos de caminhos relativos e seus caminhos absolutos equivalentes. Nestes exemplos, C:\LocalRunDataRoot é a pasta raiz de dados.

Diretório de trabalho

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

Usar o SDK da linha de comando

Interface de linha de comando do aplicativo auxiliar

No diretório do SDK\build\runtime, LocalRunHelper.exe está o aplicativo auxiliar de linha de comando que fornece interfaces para a maioria das funções de execução local comumente usadas. As opções de comando e argumento são sensíveis a maiúsculas e minúsculas. Para invocá-lo:

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

Execute LocalRunHelper.exe sem argumentos ou com a opção de ajuda 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:

• O comando fornece o nome do comando.
• O Argumento Necessário lista os argumentos que devem ser fornecidos.
• O Argumento Opcional lista os argumentos opcionais, com valores padrão. Argumentos Booleanos opcionais não possuem parâmetros, e sua presença indica o valor contrário ao seu padrão.

Valor de retorno e registro em log

O aplicativo auxiliar retorna 0 para êxito e -1 para falha. Por padrão, o auxiliar envia 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.

Configuração de variável 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. Você pode definir o argumento na linha de comando ou definir a variável de ambiente para eles.

• Defina a variável de ambiente SCOPE_CPP_SDK .

  Se você receber o Microsoft Visual C++ e o SDK do Windows instalando o Data Lake Tools 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 apontar para esse diretório. Ou copie a pasta para o outro local e especifique SCOPE_CPP_SDK como essa.

  Além de definir a variável de ambiente, você pode especificar o argumento -CppSDK quando estiver usando a linha de comando. Esse argumento substitui sua 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 quando estiver usando uma linha de comando. Esse argumento substitui sua variável de ambiente raiz de dados padrão. Você precisa adicionar esse argumento a cada linha de comando em execução para que possa substituir a variável de ambiente raiz de dados padrão para todas as operações.

Exemplos de uso de linha de comando do SDK

Compilar e executar

O comando de execução é usado para compilar o script e, em seguida, executar resultados compilados. Seus argumentos de linha de comando são uma combinação daqueles de compilar e executar.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

A seguir estão os argumentos opcionais para "run":

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 compilar e executar, você pode compilar e executar os executáveis compilados separadamente.

Compilar um script U-SQL

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

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Veja a seguir os argumentos opcionais para compilar:

Aqui estão alguns exemplos de uso.

Compile um script U-SQL:

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

Compile um script U-SQL e defina a pasta raiz de dados. Isso substituirá a variável de ambiente definida.

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

Compile um script U-SQL e defina um diretório de trabalho, um assembly de referência e um 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 resultados compilados.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Veja a seguir argumentos opcionais para execução:

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 todas localizadas no LocalRunHelper.exe. Você pode usá-los para integrar a funcionalidade do SDK do U-SQL e a estrutura de teste do C# para 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 e a configuração do teste de unidade do C#

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

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

  

• O SDK do U-SQL dá suporte apenas ao ambiente x64, certifique-se de definir o destino da plataforma de build como x64. Você pode definir isso em Propriedades do Projeto > Build > destino da Plataforma.

  

• Defina seu ambiente de teste como x64. No Visual Studio, você pode defini-lo por meio de Teste > Configurações de Teste > Arquitetura Padrão do Processador > 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 caso de teste de script U-SQL

Abaixo está o código de exemplo para o teste de script U-SQL. Para testar, você precisa preparar scripts, arquivos de entrada e 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 no LocalRunHelper.exe

LocalRunHelper.exe fornece as interfaces de programação para compilação local U-SQL, execução etc. As interfaces são listadas da seguinte maneira.

Construtor

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

Propriedades

Método

Perguntas frequentes sobre o 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.

Confira o seguinte:

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

Próximas etapas

• Para saber mais sobre o U-SQL, consulte Introdução à linguagem U-SQL do Azure Data Lake Analytics.
• Para registrar informações de diagnóstico em log, consulte Acessar logs de diagnóstico do Azure Data Lake Analytics.
• Para ver uma consulta mais complexa, consulte Analisar logs de sites usando o Azure Data Lake Analytics.
• Para exibir detalhes do trabalho, consulte Use Job Browser e Job View para trabalhos do Azure Data Lake Analytics.
• Para usar a visualização de execução de vértice, consulte Use the Vertex Execution View in Data Lake Tools for Visual Studio.