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

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 Azure Data Lake U-SQL SDK para este cenário, através do qual você pode facilmente dimensionar a execução e o teste do U-SQL. Também é possível integrar este teste U-SQL com o sistema CI (Continuous Integration) para automatizar a compilação e o teste.

Se você se preocupa em como executar manualmente e depurar scripts U-SQL com ferramentas GUI, então você pode usar o Azure Data Lake Tools for Visual Studio para isso. Você pode aprender mais sobre aqui.

Instalar o Azure Data Lake U-SQL SDK

Pode obter o SDK do Azure Data Lake U-SQL aqui no Nuget.org. E antes de o usar, deve certificar-se de que tem as dependências como se segue.

Dependências

O Data Lake U-SQL SDK 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 Visual Studio Community Edition. Você terá uma pasta \Windows Kits\10 na pasta Arquivos de Programas - por exemplo, C:\Arquivos de Programas (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 certifique-se de selecionar o SDK do Windows 10 durante a instalação. Se você tiver isso instalado com o Visual Studio, o compilador local U-SQL irá encontrá-lo automaticamente.

    SDK do Windows 10 executado localmente

  • Instale Ferramentas Data Lake para Visual Studio. Você pode encontrar os arquivos pré-empacotados do Visual C++ e do Windows SDK 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 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á-lo como está.

Compreender conceitos básicos

Raiz dos dados

A pasta raiz de dados é um "armazenamento local" para a conta de computação local. É equivalente à conta do Azure Data Lake Store de uma conta do Data Lake Analytics. Mudar para uma pasta raiz de dados diferente é como mudar para uma conta de armazenamento diferente. Se você quiser acessar dados comumente compartilhados com diferentes pastas raiz de dados, 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, funções com valor de tabela (TVFs) e assemblies.
• Procure os caminhos de entrada e saída que são 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. Nesses 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 ficheiros necessários em tempo de execução para a execução local serão copiados em sombra para este diretório de trabalho. A pasta raiz do diretório de trabalho é chamada de "ScopeWorkDir" e os arquivos sob o diretório de trabalho são os seguintes:

Usar o SDK a partir da linha de comando

Interface de linha de comando do aplicativo auxiliar

No diretório SDK\build\runtime, LocalRunHelper.exe, encontra-se a aplicação auxiliar de linha de comando que fornece interfaces para a maioria das funções de execução local mais utilizadas. 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]

Corra LocalRunHelper.exe sem argumentos ou com o alternador 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:

• Command dá o nome do comando.
• Argumento Necessário lista os argumentos que devem ser fornecidos.
• Argumento Opcional lista argumentos que são opcionais, com valores padrão. Argumentos booleanos opcionais não têm parâmetros, e a sua presença indica o contrário do seu valor 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 suporta o -MessageOut path_to_log_file argumento opcional que redireciona as saídas para um arquivo de log.

Configuração da 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ê obter o Microsoft Visual C++ e o SDK do Windows instalando o Data Lake Tools for 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 este diretório. Ou copie a pasta para o outro local e especifique SCOPE_CPP_SDK como tal.

  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 aponte 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 a variável de ambiente raiz de dados padrão. Você precisa adicionar este argumento a cada linha de comando que estiver a executar para poder substituir a variável de ambiente 'data-root' padrão em todas as operações.

Exemplos de uso de linha de comando do SDK

Compilar e executar

O comando run é usado para compilar o script e, em seguida, executar os 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 argumentos opcionais para executar:

Aqui está 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 compile é usado para compilar um script U-SQL para executáveis.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

A seguir estão 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, assembly de referência e 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]

A seguir estão argumentos opcionais para executar:

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 U-SQL e da estrutura de teste C# para dimensionar seu teste local de script U-SQL. Neste artigo, usarei o projeto de teste de unidade C# padrão para mostrar como usar essas interfaces para testar seu script U-SQL.

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

• Crie um projeto de teste de unidade C# por meio de File > New > Project > Visual C# > Test > Unit Test Project.

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

  

• O SDK U-SQL apenas suporta o ambiente x64, certifique-se de definir o destino da plataforma de compilação como x64. Você pode definir isso por meio da propriedade do projeto > do destino Build > Platform.

  

• Certifique-se de definir seu ambiente de teste como x64. No Visual Studio, você pode defini-lo por meio de Configurações de teste > teste > arquitetura de processador padrão > x64.

  

• Certifique-se de copiar 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 testes, 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 em LocalRunHelper.exe

LocalRunHelper.exe fornece as interfaces de programação para U-SQL local compilar, executar, etc. As interfaces estão listadas da seguinte forma.

Construtor

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

Propriedades

Método

FAQ sobre problemas comuns

Erro 1

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

Verifique o seguinte:

• Certifique-se de que tem um ambiente x64. A plataforma de destino de compilação e o ambiente de teste devem ser x64, consulte 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óximos passos

• Para aprender U-SQL, consulte Introdução à linguagem U-SQL do Azure Data Lake Analytics.
• Para registar informações de diagnóstico, consulte Aceder aos logs de diagnóstico para o Azure Data Lake Analytics.
• Para ver uma consulta mais complexa, consulte Analisar logs de sites usando o Azure Data Lake Analytics.
• Para ver os detalhes do trabalho, consulte Utilizar o Browser de Trabalhos e a Vista de Trabalho para trabalhos do Azure Data Lake Analytics.
• Para usar a vista de execução de vértice, consulte Usar a vista de execução de vértice nas Ferramentas do Data Lake para o Visual Studio.