使用 Azure Data Lake U-SQL SDK 執行及測試 U-SQL

開發U-SQL腳本時，通常會先在本機執行及測試U-SQL腳本，再將其提交至雲端。 Azure Data Lake 針對此案例提供名為 Azure Data Lake U-SQL SDK 的 NuGet 套件，讓您可以輕鬆地調整 U-SQL 執行和測試。 您也可以將此 U-SQL 測試與 CI （持續整合） 系統整合，以自動化編譯和測試。

如果您關心如何使用 GUI 工具手動執行 U-SQL 腳本並對其進行偵錯，您可以使用適用於 Visual Studio 的 Azure Data Lake Tools。 您可以 從這裡深入瞭解。

安裝 Azure Data Lake U-SQL SDK

您可以在 Nuget.org 這裡取得 Azure Data Lake U-SQL SDK。在使用之前，請確保您已確認以下相依項目。

依賴

Data Lake U-SQL SDK 需要下列相依性：

• Microsoft .NET Framework 4.6 或更新版本。

• Microsoft Visual C++ 14 和 Windows SDK 10.0.10240.0 或更新版本（本文中稱為 CppSDK）。 有兩種方式可取得 CppSDK：

  • 安裝 Visual Studio Community Edition。 您在 Program Files 資料夾下會有 \Windows Kits\10 資料夾，例如 C：\Program Files （x86）\Windows Kits\10。 您也會在 \Windows Kits\10\Lib 下找到 Windows 10 SDK 版本。 如果您沒有看到這些資料夾，請重新安裝Visual Studio，並確定在安裝期間選取 Windows 10 SDK。 如果您已安裝 Visual Studio，U-SQL 本機編譯程式會自動找到它。

    

  • 安裝 Data Lake Tools for Visual Studio。 您可以在 找到預先封裝的 Visual C++ 和 Windows SDK 檔案 C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.

    在此情況下，U-SQL 本機編譯程式無法自動找到相依性。 您必須指定 CppSDK 路徑。 您可以將檔案複製到另一個位置，或依目前方式使用它。

瞭解基本概念

資料根目錄

數據根資料夾是本機計算帳戶的「本地存儲」。 它相當於 Data Lake Analytics 帳戶的 Azure Data Lake Store 帳戶。 切換至不同的數據根資料夾就像切換至不同的存放區帳戶一樣。 如果您想要存取具有不同資料根資料夾的常用共享資料，您必須在腳本中使用絕對路徑。 或者，在數據根資料夾底下建立文件系統符號連結（例如，NTFS 上的 mklink ），以指向共享數據。

資料根資料夾可用來：

• 儲存本機元數據，包括資料庫、數據表、數據表值函式（TVF）和元件。
• 查閱 U-SQL 中定義為相對路徑的輸入和輸出路徑。 使用相對路徑可讓您更輕鬆地將U-SQL專案部署至 Azure。

U-SQL 中的檔案路徑

您可以在 U-SQL 腳本中使用相對路徑和本機絕對路徑。 相對路徑相對於指定的數據根資料夾路徑。 我們建議您使用 「/」 作為路徑分隔符，讓您的腳本與伺服器端相容。 以下是相對路徑及其對等絕對路徑的一些範例。 在這些範例中，C：\LocalRunDataRoot 是數據根資料夾。

工作目錄

在本機執行 U-SQL 腳本時，會在目前執行目錄中的編譯期間建立工作目錄。 除了編譯輸出之外，本機執行所需的運行時間檔案也會陰影複製到此工作目錄。 工作目錄根資料夾稱為 「ScopeWorkDir」，工作目錄下的檔案如下所示：

從命令行使用 SDK

協助應用程式的命令行介面

SDK 目錄\build\runtime, LocalRunHelper.exe 是命令列輔助應用程式，可為大部分常用的本機執行函式提供介面。 命令和參數選項都區分大小寫。 若要叫用它：

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

在不帶參數或帶有 help 選項的情況下執行 LocalRunHelper.exe 以顯示幫助資訊：

> 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

在幫助說明中：

• 命令 會提供命令的名稱。
• 必要自變數 會列出必須提供的自變數。
• 選擇性自變數 會列出具有預設值的選擇性自變數。 選擇性布爾自變數沒有參數，其外觀表示預設值為負值。

傳回值和記錄

協助程式應用程式會傳回 0 表示成功， 而 -1 則傳回失敗。 根據預設，協助程式會將所有訊息傳送至目前的控制台。 不過，大部分的命令都支援 -MessageOut path_to_log_file 選擇性自變數，將輸出重新導向至記錄檔。

環境變數設定

U-SQL 本機執行需要指定的數據根目錄作為本機存儲帳戶，以及指定的 CppSDK 路徑來處理依賴項。 您可以在命令行中設定 自變數，或為它們設定環境變數。

• 設定 SCOPE_CPP_SDK 環境變數。

  如果您透過安裝 Data Lake Tools for Visual Studio 取得 Microsoft Visual C++ 和 Windows SDK，請確認您擁有下列資料夾：

  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 命令可用來編譯腳本，然後執行編譯的結果。 其命令列參數是來自編譯和執行的參數組合。

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

以下是 run 的選擇性參數：

以下為範例：

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

除了合併編譯和執行之外，您還可以個別編譯和執行已編譯的可執行檔。

編譯 U-SQL 腳本

編譯命令是用來將U-SQL腳本編譯為可執行檔。

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

以下是 編譯時可選的參數：

以下是一些使用範例。

編譯 U-SQL 腳本：

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

編譯 U-SQL 腳本並設定數據根資料夾。 這會覆寫設定的環境變數。

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]

以下是 執行的可選參數：

以下是使用範例︰

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

搭配程式設計介面使用SDK

程序設計介面全都位於 LocalRunHelper.exe中。 您可以使用它們來整合U-SQL SDK和 C# 測試架構的功能，以調整U-SQL腳本本機測試。 在本文中，我將使用標準 C# 單元測試項目來示範如何使用這些介面來測試 U-SQL 腳本。

步驟 1：建立 C# 單元測試專案和組態

• 在 > 檔案 > 新增 > 專案 > Visual C# > 測試 單元測試專案中建立 C# 單元測試專案。

• 將 LocalRunHelper.exe 新增為項目的參考。 LocalRunHelper.exe 位於 NuGet 套件中的 \build\runtime\LocalRunHelper.exe。

  

• U-SQL SDK 僅 支援 x64 環境，請務必將建置平臺目標設定為 x64。 您可以透過 Project 屬性 > 建置 > 平台目標來設定。

  

• 請務必將測試環境設定為 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]）

性能

方法

常見問題

錯誤 1

E_CSC_SYSTEM_INTERNAL：內部錯誤！ 無法載入檔案或元件 'ScopeEngineManaged.dll' 或其其中一個相依性。 找不到指定的模組。

請檢查下列項目：

• 請確定您有 x64 環境。 建置目標平臺和測試環境應該是 x64，請參閱上述 步驟 1：建立 C# 單元測試專案和組態 。
• 請確定您已將 NugetPackage\build 底下的所有相依性檔案\runtime\ 複製到專案工作目錄。

後續步驟

• 若要瞭解 U-SQL，請參閱 開始使用 Azure Data Lake Analytics U-SQL 語言。
• 若要記錄診斷資訊，請參閱 為 Azure Data Lake Analytics 存取診斷記錄。
• 若要查看更複雜的查詢，請參閱 使用 Azure Data Lake Analytics 分析網站記錄。
• 若要檢視 Azure Data Lake Analytics 作業的詳細資訊，請參閱 作業瀏覽器及作業檢視。
• 若要使用頂點執行檢視，請參閱在 Data Lake Tools for Visual Studio 中使用頂點執行檢視。