Azure Stream Analytics işleri için .NET Standard kullanıcı tanımlı işlevler geliştirme (Kullanımdan kaldırıldı)

Önemli

.NET Azure Stream Analytics için standart kullanıcı tanımlı fonksiyonlar 30 Eylül 2024'te emekliye kaldırıldı. Bu özellik artık mevcut değil. Azure Stream Analytics için JavaScript kullanıcı tanımlı işlevlerine geçiş.

Azure Stream Analytics, olay verisi akışları üzerinde dönüştürmeler ve hesaplamalar gerçekleştirmek için SQL benzeri bir sorgu dili sunar. Dil birçok yerleşik fonksiyon içerir, ancak bazı karmaşık senaryolar daha fazla esneklik gerektirir. .NET Standard kullanıcı tanımlı fonksiyonları (UDF) kullanarak, herhangi bir .NET Standard dilinde yazılmış kendi fonksiyonlarınızı çağırarak Stream Analytics sorgu dilini genişletebilirsiniz. Karmaşık matematiksel hesaplamalar yapmak için UDF'ler kullanın, ML.NET kullanarak özel ML modellerini içe aktarın ve eksik veriler için özel ödünç mantığı kullanın.

Bu özellik emekliye bırakıldığından, .NET Standard UDF'lerin nasıl çalıştığını anlamak ve JavaScript kullanıcı tanımlı fonksiyonlara geçişinizi planlamak için bu makaleyi kullanabilirsiniz.

.NET Standard kullanıcı tanımlı fonksiyonlar hakkında

.NET Standard UDF'ler, Stream Analytics sorgu dilini özel mantıkla genişletir. UDF oluşturmadan önce, özelliğin çalıştığı bölgeleri, kullandığı paket yolunu, desteklenen tür eşlemelerini ve özellik sınırlamalarını gözden geçirin.

Azure Stream Analytics, Stream Analytics kümelerinde çalışan bulut işleri için .NET kullanıcı tanımlı fonksiyon özelliğini etkinleştirir. Standart çok kiracılı SKU'da çalışan işler bu özelliği aşağıdaki genel bölgelerde kullanabilir:

• Orta Batı ABD
• Kuzey Avrupa
• East US
• West US
• Doğu ABD 2
• West Europe

Bu özelliği başka bir bölgede kullanmak için erişim talep edin.

Herhangi bir UDF paketinin biçimi, yolu /UserCustomCode/CLR/* içerir. Azure Stream Analytics, dinamik bağlantı kütüphanelerini (DLL'leri) ve kaynakları klasör /UserCustomCode/CLR/* altında kopyalar; bu da kullanıcı DLL'lerini sistem ve Azure Stream Analytics DLL'lerinden ayırtmaya yardımcı olur. Tüm fonksiyonlar, nasıl kullanırsanız kullanın, bu paket yolunu kullanır.

C# dilinde kullanılacak Azure Stream Analytics değerlerinin bir ortamdan diğerine sıralanması gerekir. Hazırlama, UDF'nin tüm giriş parametreleri için gerçekleşir. Her Azure Stream Analytics tipin, aşağıdaki tabloda gösterilen C# dilinde karşılık gelen bir türü vardır:

Azure Stream Analytics türü	C# türü
bigint	long
yüzmek	double
nvarchar(max)	string
tarih/zaman	DateTime
Kaydet	Sözlük<dizesi, nesne>
Array	Nesne[]

Verilerin C# dilinden Azure Stream Analytics'e sıralanması gerektiğinde de aynı durum geçerlidir ve bu durum UDF'nin çıkış değerinde gerçekleşir. Aşağıdaki tablo desteklenen türleri göstermektedir:

C# türü	Azure Stream Analytics türü
long	bigint
double	yüzmek
string	nvarchar(max)
DateTime	tarih ve saat
yapı	Kaydet
nesne	Kaydet
Nesne[]	Array
Sözlük<dizesi, nesne>	Kaydet

UDF özelliğinin aşağıdaki sınırlamaları vardır:

• .NET Standard UDF'leri yalnızca Visual Studio Code veya Visual Studio'da oluşturabilir ve ardından Azure'a yayımlayabilirsiniz. .NET Standard UDF'lerin yalnızca okunabilir sürümlerini Azure portalında Fonksiyonlar bölümünde görebilirsiniz. Azure portalı, .NET Standard fonksiyonlarının oluşturulmasını desteklemiyor.
• Azure portal sorgu editörü, portalda .NET Standard UDF kullandığınızda bir hata gösteriyor.
• Dışsal REST uç noktalarına çağrı yapamazsınız, örneğin ters IP araması yapmak veya harici bir kaynaktan referans verisi çekmek gibi.
• Özel kod, Azure Stream Analytics motoruyla bağlamı paylaştığı için, özel kod, Azure Stream Analytics koduyla çelişen bir isim alanı veya DLL adı olan hiçbir şeye referans veremez. Örneğin, Newtonsoft.Json'a referans veremezsiniz.
• Azure Stream Analytics, projedeki destekleyici dosyaları, işi buluta yayımladığınızda kullandığı Kullanıcı Özel Kodu zip dosyasına kopyalar. Dekompresyon sırasında, alt klasörlerdeki tüm dosyalar buluttaki Kullanıcı Özel Kodu klasörünün köküne taşınır. Dekompresyon zip dosyasını düzleştirir.
• Kullanıcı Özel Kodu boş klasörleri desteklemez. Projedeki destekleyici dosyalara boş klasörler eklemeyin.

Visual Studio Code'da UDF geliştirme

Azure Stream Analytics için Visual Studio Code araçları UDF yazmanızı, işlerinizi yerel ortamda (hatta çevrimdışı) test etmenizi ve Stream Analytics işinizi Azure'da yayımlamanızı kolaylaştırır. .NET Standard UDF'leri Visual Studio Code'da yerel bir projeden veya yerel DLL'lerden uygulayabilirsiniz. Kullanıcı tanımlı işlevleri içeren yerel DLL'lere de başvurabilirsiniz.

Prosedürel mantık veya özyineleme gibi, ifade dilinin ötesinde bir .NET Standard dilinin tüm gücünü gerektiren karmaşık işlevler için yerel bir proje kullanın. Yerel bir proje, fonksiyon mantığını birkaç Azure Stream Analytics sorgusu arasında paylaşmanız gerektiğinde de yardımcı olur ve fonksiyonlarınızı yerel olarak hata ayıklayıp test edebilirsiniz. Aşağıdaki örnekte, CSharpUDFProject bir C# sınıfı kütüphane projesidir ve ASAUDFDemo ise CSharpUDFProject'e referans veren Azure Stream Analytics projesidir.

1. Yerel makinenizde yeni bir .NET Standard sınıf kütüphanesi oluşturun.

   

2. Kodu sınıfınıza yazın. Sınıfları kamu , nesneleri ise statik kamusal olarak tanımlayın. Aşağıdaki UDF, bir tam sayı kendi başına çarparak tam sayı karesini oluşturur.

   using System;
   
   namespace CSharpUDFProject
   {
      //
       public class Class1
       {
           public static Int64 SquareFunction(Int64 a)
           {
               return a * a;
           }
       }
   }
   

3. Azure Stream Analytics projenizde yeni bir C# fonksiyonu yapılandırma dosyası ekleyin ve C# sınıf kütüphane projesine başvurun. Fonksiyonu eklemek için Fonksiyonlar klasörünü seçin ve basılı tutun (veya sağ tıklayın), ardından Öğe Ekle'yi seçin.

   

4. Azure Stream Analytics projenize bir C# işlevi SquareFunction ekleyin.

   

5. C# fonksiyon adını girin.

   

6. C# fonksiyon yapılandırmasında, açılır menüden C# projenizi seçmek için Kütüphane projesi yolunu seç seçeneğini seçin ve Projenizi oluşturmak için Proje Oluştur seçeneğini seçin. Ardından, açılan listeden ilgili sınıf ve yöntem adını seçmek için Sınıf seç ve Yöntemi seç'i seçin. Stream Analytics sorgusunda metodlara, türlere ve fonksiyonlara atıfta bulunmak için, sınıfları kamuya açık ve nesneleri statik genel olarak tanımlayın.

   

7. Bunun yerine bir DLL'den C# UDF kullanmak için, DLL'yi seçmek için Kütüphane dll yolunu seçin, ardından Select class ve Select method seçin.

   

8. Azure Stream Analytics sorgunuzda UDF'yi çağırın.

    SELECT price, udf.SquareFunction(price)
    INTO Output
    FROM Input 
   

9. Assembly yolunu iş JobConfig.json yapılandırma dosyasında, CustomCodeStorage bölümünde yapılandırın. Bu adım yerel testler için gerekli değildir.

10. İşi Azure'a göndermeden önce, CustomCodeStorage bölümünde iş JobConfig.json yapılandırma dosyasında paket yolunu yapılandırın. CodeLens'te aboneliğinizden seç seçeneğini kullanarak aboneliğinizi seçin ve açılır menüden depolama hesabı ile konteyner adını seçin. Yolu varsayılan olarak bırakın. Bu adım yerel testler için gerekli değildir.

    

Visual Studio'da UDF geliştirme

Visual Studio'da UDF'leri ASA projesindeki CodeBehind dosyaları, yerel bir projeden UDF veya Azure depolama hesabından mevcut bir paket kullanarak uygulayabilirsiniz. Aşağıdaki örnekte, UDFTest bir C# sınıfı kütüphane projesidir ve ASAUDFDemo ise UDFTest'e referans veren Azure Stream Analytics projesidir.

CodeBehind seçeneği için, Script.asql CodeBehind dosyasına kullanıcı tanımlı fonksiyonlar yazın. Visual Studio araçları, CodeBehind dosyasını otomatik olarak bir assembly dosyasına derler. Araçlar, montajları zip dosyası olarak paketler ve işinizi Azure'a gönderdiğinizde depolama hesabınıza yükler. CodeBehind kullanarak C# UDF yazmayı öğrenmek için C# UDF for Stream Analytics Edge iş eğitimini takip edin.

1. Çözümünüzde yeni bir .NET Standard sınıf kütüphanesi oluşturun.

   

2. Kodu sınıfınıza yazın. Sınıfları kamu , nesneleri ise statik kamusal olarak tanımlayın.

3. Projenizi derleyin. Araçlar, bin klasöründeki tüm eserleri bir zip dosyasına paketler ve zip dosyasını depolama hesabına yükler. Dış referanslar için NuGet paketi yerine bir assembly referansı kullanın.

4. Azure Stream Analytics projenizdeki yeni sınıfa başvurun.

5. Azure Stream Analytics projenize yeni bir işlev ekleyin.

6. JobConfig.json iş yapılandırma dosyasında assembly yolunu yapılandırın. Assembly yolunu Local Project Reference veya CodeBehind olarak ayarlayın.

7. Hem işlev projesini hem de Azure Stream Analytics projesini yeniden oluşturun.

8. C# projenizi Azure Stream Analytics sorgusundan C# UDF'nize bir referans ekleyebilecek şekilde oluşturun.

   

9. ASA projesine C# projesine yönelik referansı ekleyin. Referanslar düğümünü seçin ve basılı tutun (veya sağ tıklayın), ardından Referans Ekle'yi seçin.

   

10. Listeden C# proje adını seçin.

    

11. UDFTest'inÇözüm Gezgini'daReferanslar bölümünde göründüğünü doğrulayın.

    

12. Fonksiyonlar klasörünü seçin ve basılı tutun (veya sağ tıklayın), ardından Yeni Öğe'i seçin.

    

13. Azure Stream Analytics projenize bir C# işlevi SquareFunction.json ekleyin.

    

14. Çözüm Gezgini'da yapılandırma diyalogunu görüntülemek için bu fonksiyonu açın.

    

15. C# işlevi yapılandırmasında ASA Proje Başvurusu'ndan yükle'yi ve açılan listeden ilgili derleme, sınıf ve yöntem adlarını seçin. Stream Analytics sorgusunda metodlara, türlere ve fonksiyonlara atıfta bulunmak için, sınıfları kamuya açık ve nesneleri statik genel olarak tanımlayın.

    

Mevcut .NET Standard UDF paketlerini yapılandırma

.NET Standard UDF'leri herhangi bir IDE'de oluşturabilir ve bunları Azure Stream Analytics sorgusundan çağırabilirsiniz. Assembly zip paketlerini Azure depolama hesabınıza yükledikten sonra, depolama bilgilerini Stream Analytics iş yapılandırmasına dahil ederek Azure Stream Analytics sorgularındaki fonksiyonları kullanabilirsiniz. Bu seçenekle işlevi yerel olarak test edemezsiniz çünkü Visual Studio araçları paketinizi indirmez. Servis, paket yolunu doğrudan ayrıştırır. Mevcut bir paketi kullanmak için:

1. Kodunuzu derleyin ve tüm DLL'leri şu yolu /UserCustomCode/CLR/*kullanarak paketleyin.

2. Azure depolama hesabınızdaki konteynerin kök noktasına yükleyinUserCustomCode.zip.

3. JobConfig.json görev yapılandırma dosyasında, Kullanıcı Tanımlı Kod Yapılandırması bölümünü genişletin.

4. Konfigürasyonu aşağıdaki önerilen değerlerle doldurun.

   Setting	Önerilen değer
   Genel Depolama Ayarları Kaynağı	Geçerli hesaptan veri kaynağı seçme
   Genel Depolama Ayarları Aboneliği	< aboneliğiniz >
   Genel Depolama Ayarları Depolama Hesabı	< depolama hesabınız >
   Özel Kod Depolama Ayarları Kaynağı	Geçerli hesaptan veri kaynağı seçme
   Özel Kod Depolama Ayarları Depolama Hesabı	< depolama hesabınız >
   Özel Kod Depolama Ayarları Kapsayıcısı	< depolama kapsayıcınız >
   Özel Kod Derleme Kaynağı	Buluttan mevcut derleme paketleri
   Özel Kod Derleme Kaynağı	UserCustomCode.zip

StreamingContext sınıfıyla özel bilgileri loglayın

Günlük kaydı mekanizmasını kullanarak, bir görev çalışırken özel bilgileri kaydedebilirsiniz. Özel kodun doğruluğunu gerçek zamanlı olarak hata ayıklamak veya değerlendirmek için log verilerini kullanın. Günlük iletilerini yayımlamak ve bunlara erişmek için aşağıdaki adımları izleyin:

1. Tanılama bilgilerini StreamingDiagnostics.WriteError işlevini kullanarak yayımlamak için StreamingContext sınıfını kullanın. Aşağıdaki kod, Azure Stream Analytics'in açığa çıkardığı arayüzü gösterir.

   public abstract class StreamingContext
   {
       public abstract StreamingDiagnostics Diagnostics { get; }
   }
   
   public abstract class StreamingDiagnostics
   {
       public abstract void WriteError(string briefMessage, string detailedMessage);
   }
   

2. StreamingContext öğesini UDF yöntemine girdi parametresi olarak iletin ve özel günlük bilgilerini yayımlamak için bunu UDF içinde kullanın. Aşağıdaki örnekte, MyUdfMethod sorgu tarafından sağlanan bir veri girdisi ve çalışma zamanı motorunun sağladığı bir bağlam girdisi StreamingContextolarak tanımlanır.

   public static long MyUdfMethod(long data, StreamingContext context)
   {
       // write log
       context.Diagnostics.WriteError("User Log", "This is a log message");
   
       return data;
   }
   

3. Sorunuz üzerinden UDF'yi arayın. SQL sorgusunda değeri StreamingContext aktarmanıza gerek yok, çünkü Azure Stream Analytics, giriş parametresi varsa otomatik olarak bir bağlam nesnesi sağlar. MyUdfMethod Kullanım değişmez, aşağıdaki sorguda gösterildiği gibi.

   SELECT udf.MyUdfMethod(input.value) as udfValue FROM input
   

4. Günlük iletilerine tanılama günlükleri üzerinden erişin.

İlgili içerik

• Öğretici: Azure Stream Analytics işine yönelik C# kullanıcı tanımlı bir işlev yazma (Önizleme)
• Öğretici: Azure Stream Analytics JavaScript kullanıcı tanımlı işlevleri
• Visual Studio Code'da Azure Stream Analytics işi oluşturma