Azure Data Lake U-SQL SDK ile U-SQL çalıştırma ve test etme

U-SQL betiği geliştirirken, U-SQL betiğini buluta göndermeden önce yerel olarak çalıştırmak ve test etmek yaygın bir işlemdir. Azure Data Lake, bu senaryo için U-SQL çalıştırma ve testlerini kolayca ölçeklendirebileceğiniz Azure Data Lake U-SQL SDK adlı bir NuGet paketi sağlar. Derleme ve testi otomatikleştirmek için bu U-SQL testini CI (Sürekli Tümleştirme) sistemiyle tümleştirmek de mümkündür.

GUI araçlarıyla U-SQL betiğini el ile çalıştırmayı ve hatalarını ayıklamayı düşünüyorsanız bunun için Visual Studio için Azure Data Lake Araçları kullanabilirsiniz. Buradan daha fazla bilgi edinebilirsiniz.

Azure Data Lake U-SQL SDK'sı yükleme

Azure Data Lake U-SQL SDK'sını buradan Nuget.org alabilirsiniz. Bunu kullanmadan önce bağımlılıklarınız olduğundan emin olmanız gerekir.

Bağımlılıklar

Data Lake U-SQL SDK'sı aşağıdaki bağımlılıkları gerektirir:

• Microsoft .NET Framework 4.6 veya üzeri.

• Microsoft Visual C++ 14 ve Windows SDK 10.0.10240.0 veya üzeri (bu makalede CppSDK olarak adlandırılır). CppSDK almanın iki yolu vardır:

  • Visual Studio Community Edition'ı yükleyin. Program Dosyaları klasörünün altında bir \Windows Kits\10 klasörünüz olur; örneğin, C:\Program Files (x86)\Windows Kits\10. Windows 10 SDK sürümünü \Windows Kits\10\Lib altında da bulabilirsiniz. Bu klasörleri görmüyorsanız Visual Studio'yu yeniden yükleyin ve yükleme sırasında Windows 10 SDK'yı seçtiğinizden emin olun. Bunu Visual Studio'da yüklediyseniz, U-SQL yerel derleyicisi bunu otomatik olarak bulur.

    

  • Visual Studio için Data Lake Araçları'nı yükleyin. Önceden paketlenmiş Visual C++ ve Windows SDK dosyalarını adresinde bulabilirsinizC:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.

    Bu durumda, U-SQL yerel derleyicisi bağımlılıkları otomatik olarak bulamaz. Bunun için CppSDK yolunu belirtmeniz gerekir. Dosyaları başka bir konuma kopyalayabilir veya olduğu gibi kullanabilirsiniz.

Temel kavramları anlama

Veri kökü

Veri kökü klasörü, yerel işlem hesabı için bir "yerel depodur". Bu, bir Data Lake Analytics hesabının Azure Data Lake Store hesabına eşdeğerdir. Farklı bir veri kökü klasörüne geçmek, farklı bir mağaza hesabına geçmek gibidir. Yaygın olarak paylaşılan verilere farklı veri kök klasörleriyle erişmek istiyorsanız, betiklerinizde mutlak yollar kullanmanız gerekir. Alternatif olarak, paylaşılan verilere işaret etmek için veri kökü klasörünün altında dosya sistemi sembolik bağlantıları (örneğin, NTFS'de mklink ) oluşturun.

Veri-kök klasörü aşağıdakiler için kullanılır:

• Veritabanları, tablolar, tablo değerli işlevler (TVF'ler) ve derlemeler dahil olmak üzere yerel meta verileri depolayın.
• U-SQL'de göreli yollar olarak tanımlanan giriş ve çıkış yollarını arayın. Göreli yolları kullanmak, U-SQL projelerinizi Azure'a dağıtmanızı kolaylaştırır.

U-SQL'de dosya yolu

U-SQL betiklerinde hem göreli yol hem de yerel mutlak yol kullanabilirsiniz. Göreli yol, belirtilen veri kökü klasör yoluna göredir. Betiklerinizi sunucu tarafıyla uyumlu hale getirmek için yol ayırıcı olarak "/" kullanmanızı öneririz. Göreli yollara ve bunların eşdeğer mutlak yollarına bazı örnekler aşağıda verilmiştir. Bu örneklerde, C:\LocalRunDataRoot veri kökü klasörüdür.

Çalışma dizini

U-SQL betiğini yerel olarak çalıştırırken, geçerli çalışan dizin altında derleme sırasında bir çalışma dizini oluşturulur. Derleme çıkışlarına ek olarak, yerel yürütme için gereken çalışma zamanı dosyaları bu çalışma dizinine gölge kopyalanır. Çalışma dizini kök klasörü "ScopeWorkDir" olarak adlandırılır ve çalışma dizini altındaki dosyalar aşağıdaki gibidir:

Komut satırından SDK'yi kullanma

Yardımcı uygulamanın komut satırı arabirimi

SDK dizini\build\runtime altında LocalRunHelper.exe, yaygın olarak kullanılan yerel çalıştırma işlevlerinin çoğuna arabirimler sağlayan komut satırı yardımcı uygulamasıdır. Hem komut hem de bağımsız değişken anahtarları büyük/küçük harfe duyarlıdır. Çağırmak için:

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

LocalRunHelper.exe bağımsız değişken olmadan veya yardım bilgilerini göstermek için yardım anahtarıyla çalıştırın:

> 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

Yardım bilgilerinde:

• Komut , komutun adını verir.
• Gerekli Bağımsız Değişken , sağlanması gereken bağımsız değişkenleri listeler.
• İsteğe Bağlı Bağımsız Değişken , varsayılan değerlerle isteğe bağlı bağımsız değişkenleri listeler. İsteğe bağlı Boole bağımsız değişkenlerinin parametreleri yoktur ve bunların görünümleri varsayılan değerleri için negatif anlamına gelir.

Dönüş değeri ve günlüğe kaydetme

Yardımcı uygulama başarı için 0 , hata için -1 döndürür. Varsayılan olarak, yardımcı tüm iletileri geçerli konsola gönderir. Ancak, komutların çoğu çıkışları bir günlük dosyasına yeniden yönlendiren -MessageOut path_to_log_file isteğe bağlı bağımsız değişkenini destekler.

Ortam değişkeni yapılandırma

U-SQL yerel çalıştırması, yerel depolama hesabı olarak belirtilen bir veri köküne ve bağımlılıklar için belirtilen bir CppSDK yoluna ihtiyaç duyar. Hem komut satırında bağımsız değişkeni ayarlayabilir hem de ortam değişkenini ayarlayabilirsiniz.

• SCOPE_CPP_SDK ortam değişkenini ayarlayın.

  Visual Studio için Data Lake Araçları'nı yükleyerek Microsoft Visual C++ ve Windows SDK alırsanız aşağıdaki klasöre sahip olduğunuzu doğrulayın:

  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

  Bu dizine işaret etmek için SCOPE_CPP_SDK adlı yeni bir ortam değişkeni tanımlayın. Veya klasörü diğer konuma kopyalayın ve SCOPE_CPP_SDK olarak belirtin.

  Ortam değişkenini ayarlamaya ek olarak, komut satırını kullanırken -CppSDK bağımsız değişkenini belirtebilirsiniz. Bu bağımsız değişken, varsayılan CppSDK ortam değişkeninizin üzerine yazar.

• LOCALRUN_DATAROOT ortam değişkenini ayarlayın.

  Veri köküne işaret eden LOCALRUN_DATAROOT adlı yeni bir ortam değişkeni tanımlayın.

  Ortam değişkenini ayarlamaya ek olarak, komut satırı kullanırken veri-kök yolu ile -DataRoot bağımsız değişkenini belirtebilirsiniz. Bu bağımsız değişken, varsayılan veri kökü ortam değişkeninizin üzerine yazar. Tüm işlemler için varsayılan veri kökü ortam değişkeninin üzerine yazabilmek için bu bağımsız değişkeni çalıştırdığınız her komut satırına eklemeniz gerekir.

SDK komut satırı kullanım örnekleri

Derleme ve çalıştırma

Betiği derlemek ve ardından derlenmiş sonuçları yürütmek için run komutu kullanılır. Komut satırı bağımsız değişkenleri , derleme ve yürütme için kullanılanların birleşimidir.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

Çalıştırma için isteğe bağlı bağımsız değişkenler şunlardır:

Aşağıda bir örnek verilmiştir:

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

Derleme ve yürütmeyi birleştirmenin yanı sıra, derlenmiş yürütülebilir dosyaları ayrı olarak derleyebilir ve yürütebilirsiniz.

U-SQL betiği derleme

Derleme komutu, yürütülebilir dosyalara U-SQL betiği derlemek için kullanılır.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Derleme için isteğe bağlı bağımsız değişkenler şunlardır:

Aşağıda bazı kullanım örnekleri verilmiştir.

U-SQL betiği derleme:

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

Bir U-SQL betiği derleyin ve data-root klasörünü ayarlayın. Bu, ayarlanan ortam değişkeninin üzerine yazar.

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

Bir U-SQL betiği derleyin ve bir çalışma dizini, başvuru derlemesi ve veritabanı ayarlayın:

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

Derlenmiş sonuçları yürütme

Execute komutu derlenmiş sonuçları yürütmek için kullanılır.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Yürütme için isteğe bağlı bağımsız değişkenler şunlardır:

Kullanım örneği aşağıda verilmiştir:

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

SDK'yi programlama arabirimleriyle kullanma

Programlama arabirimlerinin tümü LocalRunHelper.exe bulunur. U-SQL SDK'sının işlevselliğini ve C# test çerçevesini tümleştirerek U-SQL betik yerel testinizi ölçeklendirin. Bu makalede standart C# birim testi projesini kullanarak U-SQL betiğinizi test etmek için bu arabirimlerin nasıl kullanılacağını göstereceğim.

1. Adım: C# birim testi projesi ve yapılandırması oluşturma

• Dosya Yeni Projesi Visual C# Test Birimi Test > Projesi aracılığıyla bir C# > birim testi projesi oluşturun.>>>

• LocalRunHelper.exe projeye başvuru olarak ekleyin. LocalRunHelper.exe, NuGet paketindeki \build\runtime\LocalRunHelper.exe konumunda bulunur.

  

• U-SQL SDK yalnızca x64 ortamını destekler, derleme platformu hedefini x64 olarak ayarladığınızdan emin olun. Bunu Project Özellik > Derleme > Platformu hedefi aracılığıyla ayarlayabilirsiniz.

  

• Test ortamınızı x64 olarak ayarladığınızdan emin olun. Visual Studio'da Test Test Ayarları > Varsayılan İşlemci Mimarisi > x64 aracılığıyla > ayarlayabilirsiniz.

  

• NugetPackage\build\runtime\ altındaki tüm bağımlılık dosyalarını genellikle ProjectFolder\bin\x64\Debug altındaki proje çalışma dizinine kopyaladığınızdan emin olun.

2. Adım: U-SQL betik test çalışması oluşturma

Aşağıda U-SQL betik testi için örnek kod verilmiştir. Test için betikleri, giriş dosyalarını ve beklenen çıkış dosyalarını hazırlamanız gerekir.

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 programlama arabirimleri

LocalRunHelper.exe, U-SQL yerel derleme, çalıştırma vb. için programlama arabirimleri sağlar. Arabirimler aşağıdaki gibi listelenir.

Oluşturucu

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

Özellikler

Yöntem

Yaygın sorun hakkında SSS

Hata 1

E_CSC_SYSTEM_INTERNAL: İç hata! 'ScopeEngineManaged.dll' dosyası veya derlemesi ya da bağımlılıklarından biri yüklenemedi. Belirtilen modül bulunamadı.

Aşağıdakileri denetleyin:

• x64 ortamınız olduğundan emin olun. Derleme hedef platformu ve test ortamı x64 olmalıdır. Yukarıdaki 1. Adım: C# birim testi projesi ve yapılandırması oluşturma bölümüne bakın.
• Proje çalışma dizinine NugetPackage\build\runtime\ altındaki tüm bağımlılık dosyalarını kopyaladığınızdan emin olun.

Sonraki adımlar

• U-SQL öğrenmek için bkz. Azure Data Lake Analytics U-SQL dili ile çalışmaya başlama.
• Tanılama bilgilerini günlüğe kaydetmek için bkz. Azure Data Lake Analytics için tanılama günlüklerine erişme.
• Daha karmaşık bir sorgu görmek için bkz. Azure Data Lake Analytics kullanarak web sitesi günlüklerini analiz etme.
• İş ayrıntılarını görüntülemek için bkz. Azure Data Lake Analytics işleri için İş Tarayıcısı ve İş Görünümü'nü kullanma.
• Köşe yürütme görünümünü kullanmak için bkz. Visual Studio için Data Lake Araçları'nda Köşe Yürütme Görünümünü Kullanma.