Выполнение и тестирование U-SQL с помощью пакета SDK Azure Data Lake для U-SQL

Важно!

Поддержка Azure Data Lake Analytics прекращена 29 февраля 2024 г. Дополнительные сведения см. в этом объявлении.

Для аналитики данных ваша организация может использовать Azure Synapse Analytics или Microsoft Fabric.

При разработке скрипта U-SQL обычно выполняется и тестируется скрипт U-SQL локально перед его отправкой в облако. Azure Data Lake предоставляет пакет NuGet с именем Пакет SDK U-SQL azure Data Lake для этого сценария, с помощью которого можно легко масштабировать запуск и тестирование U-SQL. Вы также можете интегрировать этот тест U-SQL с системой непрерывной интеграции для автоматизации компиляции и тестирования.

Если вас интересует, как вручную выполнить локальный запуск и отладку сценария U-SQL с помощью инструментов с графическим интерфейсом пользователя, то для этого можно использовать средства Azure Data Lake для Visual Studio. Дополнительные сведения см. здесь.

Установка пакета SDK Azure Data Lake для U-SQL

Пакет SDK U-SQL для Azure Data Lake можно получить на этой странице сайта NuGet.org. Перед его использованием проверьте или создайте указанные ниже зависимости.

Зависимости

Для пакета SDK U-SQL для Data Lake требуются следующие зависимости:

• Microsoft .NET Framework 4.6 или более поздней версии.

• Microsoft Visual C++ 14 и пакет SDK для Windows 10.0.10240.0 или более поздняя версия (в этой статье он называется пакетом CppSDK). Пакет CppSDK можно получить двумя способами.

  • Установка выпуска Visual Studio Community. В папке Program Files будет папка \Windows Kits\10, например C:\Program Files (x86)\Windows Kits\10. Кроме того, в папке \Windows Kits\10\Lib находится версия пакета SDK для Windows 10. Если у вас нет этих папок, переустановите Visual Studio и обязательно выберите пакет SDK для Windows 10 в процессе установки. Если он установлен вместе с Visual Studio, локальный компилятор U-SQL обнаружит его автоматически.

    

  • Установка средств Data Lake для Visual Studio. Предварительно упакованные файлы пакета SDK для Windows и Visual C++ можно получить здесь: C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.

    В этом случае локальный компилятор U-SQL не может автоматически найти зависимости. Вам потребуется указать путь к CppSDK. Можно скопировать файлы в другое место или просто использовать стандартный путь.

Основные понятия

Корневая папка данных

Корневая папка данных служит "локальным хранилищем" для локальной учетной записи среды вычислений. Она действует так же, как учетная запись Azure Data Lake Store в учетной записи Data Lake Analytics. Переход на другую корневую папку данных аналогичен переходу на другую учетную запись хранения. Если вам нужен доступ к данным, которые совместно используются различными корневыми папками данных, следует использовать в скриптах абсолютные пути или создать в корневой папке данных символические ссылки файловой системы (например, с помощью команды mklink для файловой системы NTFS), указывающие на совместно используемые данные.

Корневая папка данных используется в следующих целях.

• Хранение локальных метаданных, включая базы данных, таблицы, функции с табличным значением (TVF) и сборки.
• Поиск путей ввода-вывода, которые определяются как относительные пути в U-SQL. Использование относительных путей упрощает развертывание проектов U-SQL в Azure.

Путь к файлу в U-SQL

В скриптах U-SQL можно использовать как относительные, так и абсолютные локальные пути. Относительный путь задается относительно пути к выбранной корневой папке данных. Мы советуем использовать в качестве разделителя пути символ "/", чтобы обеспечить совместимость скриптов с выполнением на стороне сервера. Ниже приведены некоторые примеры относительных путей и их абсолютные эквиваленты. В этих примерах предполагается, что мы используем корневую папку данных C:\LocalRunDataRoot.

Относительный путь	Абсолютный путь
/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

Рабочий каталог

Если сценарий U-SQL выполняется локально, то рабочий каталог создается во время компиляции в текущем каталоге выполнения. В него записываются выходные данные процесса компиляции, а также здесь создается теневая копия всех файлов среды выполнения, которые требуются для локального выполнения. Корневая папка рабочего каталога называется ScopeWorkDir, и рабочий каталог содержит следующие файлы:

Каталог/файл	Каталог/файл	Каталог/файл	Определение	Описание
C6A101DDCB470506			Хэш-строка версии среды выполнения	Теневая копия файлов среды выполнения, необходимых для локального выполнения
	Script_66AE4909AA0ED06C		Имя скрипта и хэш-строка пути к скрипту	Выходные данные компиляции и ведение журнала шагов выполнения
		_script_.abr	Выходные данные компилятора	Файл Algebra
		_ScopeCodeGen_.*	Выходные данные компилятора	Созданный управляемый код
		_ScopeCodeGenEngine_.*	Выходные данные компилятора	Созданный собственный код
		referenced assemblies	Ссылка на сборку	Связанные файлы сборок.
		deployed_resources	Развертывание ресурсов	Файлы развертывания ресурсов
		xxxxxxxx.xxx[1..n]_*.*	Журнал выполнения	Журнал шагов выполнения

Использование пакета SDK из командной строки

Интерфейс командной строки вспомогательного приложения

Файл LocalRunHelper.exe в каталоге directory\build\runtime пакета SDK содержит вспомогательное приложение командной строки, которое предоставляет интерфейсы для большинства распространенных функций локального выполнения. Параметры команды и аргументов чувствительны к регистру. Для вызова вспомогательного приложения выполните следующую команду:

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

Если запустить LocalRunHelper.exe без аргументов или с параметром help, отобразятся справочные сведения:

> 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

Эта справочная информация содержит следующие элементы.

• Command определяет имя выполняемой команды.
• Required Argument перечисляет обязательные аргументы.
• Optional Argument перечисляет необязательные аргументы и приводит для них значения по умолчанию. Если необязательный аргумент имеет тип логического значения, он не принимает дополнительные параметры, и тогда его наличие определяет поведение, противоположное значению по умолчанию.

Возвращаемое значение и ведение журнала

Вспомогательное приложение возвращает значение 0 в случае успешного выполнения или -1 в случае сбоя. По умолчанию вспомогательное приложение отправляет все служебные сообщения в текущую консоль. Однако большинство команд поддерживает необязательный аргумент -MessageOut path_to_log_file, который позволяет перенаправлять выходные данные в файл журнала.

Настройка переменной среды

Для локального выполнения U-SQL требуется указанный корень данных в качестве локальной учетной записи хранения и указанный путь CppSDK для зависимостей. Эти значения можно задать с помощью аргумента в командной строке или переменной среды.

• Настройка переменной среды SCOPE_CPP_SDK.

  Если для получения Microsoft Visual C++ и пакета SDK для Windows вы установили средства Data Lake для Visual Studio, убедитесь в наличии следующей папки:

  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

  Определите новую переменную среды с именем SCOPE_CPP_SDK, которая будет указывать на этот каталог. Можно также скопировать эту папку в другое расположение и указать новый путь к ней в переменной среды SCOPE_CPP_SDK.

  Кроме настройки переменной среды, вы можете использовать аргумент -CppSDK в командной строке. Этот аргумент переопределяет используемую по умолчанию переменную среды CppSDK.

• Настройка переменной среды LOCALRUN_DATAROOT.

  Определите новую переменную среды с именем LOCALRUN_DATAROOT, которая будет указывать на корневую папку данных.

  Кроме настройки переменной среды, вы можете использовать аргумент -DataRoot в командной строке, который указывает на корневую папку данных. Этот аргумент переопределяет используемую по умолчанию переменную среды, задающую путь к корневой папке данных. Этот аргумент необходимо добавлять во все выполняемые командные строки, чтобы переопределить используемую по умолчанию переменную среды, задающую путь к корневой папке данных, для всех операций.

Примеры использования командной строки пакета SDK

Компиляция и запуск

Команда run компилирует скрипт и выполняет программу, полученную в результате компиляции. Эта команда принимает все аргументы командной строки, которые доступны для команд compile и execute.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

Ниже приведены необязательные аргументы для команды run.

Аргумент	Значение по умолчанию	Описание
-CodeBehind	Неверно	Сценарий содержит код программной части .cs.
-CppSDK		Каталог CppSDK.
-DataRoot	Переменная среды DataRoot	Корневая папка для локального выполнения. По умолчанию используется значение из переменной среды LOCALRUN_DATAROOT.
-MessageOut		Сохранение в файл всех сообщений, предназначенных для вывода на консоль.
-Parallel	1	Запуск плана с указанным значением параллелизма.
-References		Список путей к дополнительным справочным сборкам или файлам данных кода программной части с разделителем ";".
-UdoRedirect	Неверно	Создание конфигурации перенаправления сборки Udo.
-UseDatabase	master	База данных, в которой нужно регистрировать временную сборку кода программной части.
-Verbose	Неверно	Отображение подробных выходных данных среды выполнения.
-WorkDir	Текущий каталог	Задает каталог для работы и выходных данных компилятора.
-RunScopeCEP	0	Используемый режим ScopeCEP.
-ScopeCEPTempPath	temp	Временный путь для потоковой передачи данных.
-OptFlags		Разделенный запятыми список флагов оптимизатора.

Ниже приведен пример:

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

Операции compile и execute можно также выполнять по отдельности.

Компиляция скрипта U-SQL

Команда compile позволяет выполнить компиляцию скрипта U-SQL в исполняемые файлы.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Ниже приведены необязательные аргументы для команды compile.

Аргумент	Описание
-CodeBehind [значение по умолчанию False]	Сценарий содержит код программной части .cs.
-CppSDK [значение по умолчанию "]	Каталог CppSDK.
-DataRoot [значение по умолчанию: переменная среды DataRoot]	Корневая папка для локального выполнения. По умолчанию используется значение из переменной среды LOCALRUN_DATAROOT.
-MessageOut [значение по умолчанию "]	Сохранение в файл всех сообщений, предназначенных для вывода на консоль.
-References [значение по умолчанию "]	Список путей к дополнительным справочным сборкам или файлам данных кода программной части с разделителем ";".
-Shallow [значение по умолчанию False]	Неполная компиляция.
-UdoRedirect [значение по умолчанию False]	Создание конфигурации перенаправления сборки Udo.
-UseDatabase [значение по умолчанию master]	База данных, в которой нужно регистрировать временную сборку кода программной части.
-WorkDir [значение по умолчанию: текущий каталог]	Задает каталог для работы и выходных данных компилятора.
-RunScopeCEP [значение по умолчанию: "0"]	Используемый режим ScopeCEP.
-ScopeCEPTempPath [значение по умолчанию: "temp"]	Временный путь для потоковой передачи данных.
-OptFlags [значение по умолчанию: "]	Разделенный запятыми список флагов оптимизатора.

Вот несколько примеров использования команды.

Компиляция скрипта U-SQL:

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

Компиляция скрипта U-SQL с определенной корневой папкой данных Это приведет к перезаписи переменной среды set.

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

Компиляция скрипта U-SQL с определенным рабочим каталогом и ссылками на сборку и базу данных:

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

Выполнение скомпилированного результата

Команда execute используется для выполнения скомпилированного результата.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Ниже приведены необязательные аргументы для команды execute.

Аргумент	Значение по умолчанию	Описание
-DataRoot	''	Корневая папка для обработки метаданных. По умолчанию используется переменная среды LOCALRUN_DATAROOT.
-MessageOut	''	Сохранение в файл всех сообщений, предназначенных для вывода на консоль.
-Parallel	1	Показатель выполнения созданных шагов локального выполнения на указанном уровне параллелизма.
-Verbose	False	Показатель отображения подробных выходных данных среды выполнения.

Пример использования этой команды:

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

Использование пакета SDK с программными интерфейсами

Все программные интерфейсы размещены в LocalRunHelper.exe. Они позволяют объединить функциональность пакетов SDK U-SQL и тестовой платформы C#, чтобы масштабировать локальное тестирование скрипта U-SQL. В этой статье я использую стандартный проект модульного теста C#, чтобы показать, как использовать эти интерфейсы для тестирования скрипта U-SQL.

Шаг 1. Создание проекта модульного теста C# и его настройка

• Создайте проект модульного теста C#, используя файл > Новый > проект > Visual C# > Test > Unit Test Project.

• Добавьте в проект ссылку на LocalRunHelper.exe. LocalRunHelper.exe находится в \build\runtime\LocalRunHelper.exe в пакете NuGet.

  

• Пакет SDK U-SQL поддерживает только среду x64. Убедитесь, что целевая платформа сборки имеет значение x64. Это можно задать с помощью целевой платформы сборки > свойств > проекта.

  

• Обязательно задайте тестовую среду x64. В Visual Studio его можно задать с помощью параметров тестирования > Архитектура > процессора > по умолчанию x64.

  

• Обязательно скопируйте все файлы зависимостей в разделе NugetPackage\build\runtime\ в рабочий каталог проекта, который обычно находится в папке ProjectFolder\bin\x64\Debug.

Шаг 2. Создание тестового случая сценария U-SQL

Ниже приведен пример кода для теста сценария U-SQL. Для тестирования необходимо подготовить сценарии, входные файлы и ожидаемые выходные файлы.

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

Программные интерфейсы в LocalRunHelper.exe

LocalRunHelper.exe предоставляет программные интерфейсы для локальной компиляции, выполнения U-SQL и т. д. Все эти интерфейсы перечислены ниже.

Конструктор

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

Параметр	Тип	Описание
messageOutput	System.IO.TextWriter	Для вывода сообщений задайте значение NULL, чтобы использовать консоль.

Свойства

Свойство	Тип	Описание
AlgebraPath	строка	Путь к файлу алгебры (он является одним из результатов компиляции).
CodeBehindReferences	строка	Если скрипт содержит другие ссылки на код, укажите пути, разделенные ";"
CppSdkDir	строка	Каталог пакета CppSDK.
CurrentDir	строка	Текущий каталог.
DataRoot	строка	Путь к корневой папке данных.
DebuggerMailPath	строка	Путь к почтовому слоту отладчика.
GenerateUdoRedirect	bool	Указывает, нужно ли создавать конфигурацию, переопределяющую пути перенаправления для загрузки сборки
HasCodeBehind	bool	Позволяет указать, содержит ли сценарий код программной части.
InputDir	строка	Каталог для входных данных.
MessagePath	строка	Путь к файлу дампа сообщений.
OutputDir	строка	Каталог для выходных данных.
Parallelism	INT	Значение параллелизма для вычислений алгебры.
ParentPid	INT	Идентификатор процесса родительского объекта, который отслеживает служба для выполнения выхода. Задайте значение 0 или отрицательное значение, чтобы этот параметр игнорировался.
ResultPath	строка	Путь к файлу дампа результатов.
RuntimeDir	строка	Каталог среды выполнения.
ScriptPath	строка	Расположение сценария.
Shallow	bool	Позволяет задать выполнение неполной компиляции.
TempDir	строка	Каталог temp
UseDataBase	строка	Укажите базу данных для регистрации временной сборки кода программной части. По умолчанию: база данных master.
WorkDir	строка	Предпочитаемый рабочий каталог.

Метод

Метод	Описание	Возвращает	Параметр
public bool DoCompile()	Компиляция сценария U-SQL.	В случае успешного выполнения возвращает True.
public bool DoExec()	Выполнение скомпилированного результата.	В случае успешного выполнения возвращает True.
public bool DoRun()	Выполнение сценария U-SQL (компиляция и выполнение).	В случае успешного выполнения возвращает True.
public bool IsValidRuntimeDir(string path)	Проверяет, является ли заданный путь допустимым путем среды выполнения.	Значение True, если путь допустимый.	Путь к каталогу среды выполнения.

Часто задаваемые вопросы о распространенных проблемах

Ошибка 1

E_CSC_SYSTEM_INTERNAL: Внутренняя ошибка! Не удалось загрузить файл или сборку "ScopeEngineManaged.dll" либо одну из ее зависимостей. Не найден указанный модуль.

Проверьте следующее:

• Убедитесь, что используется среда x64. Необходимо использовать целевую платформу сборки x64 и тестовую среду x64. Ознакомьтесь с разделом Шаг 1. Создание проекта модульного теста C# и его настройка выше.
• Убедитесь, что все файлы зависимостей из NugetPackage\build\runtime были скопированы в рабочий каталог проекта.

Дальнейшие действия

• Для знакомства с U-SQL см. статью о начале работы с языком U-SQL для Azure Data Lake Analytics.
• Сведения о том, как записывать диагностические данные в журнал, см. в статье Доступ к журналам диагностики для Azure Data Lake Analytics.
• Более сложный запрос см. в руководстве Анализ журналов веб-сайта с помощью службы Azure Data Lake Analytics.
• Для просмотра сведений о заданиях см. статью Использование браузера и представления для заданий Azure Data Lake Analytics.
• Дополнительные сведения см. в статье Использование представления выполнения вершин в инструментах Data Lake для Visual Studio.