Kembangkan fungsi yang ditentukan pengguna .NET Standard untuk job Azure Stream Analytics (Dihentikan)

Penting

Fungsi .NET Standard yang didefinisikan pengguna untuk Azure Stream Analytics dihentikan pada 30 September 2024. Fitur ini sudah tidak tersedia lagi. Transisi ke fungsi yang didefinisikan pengguna JavaScript untuk Azure Stream Analytics.

Azure Stream Analytics menawarkan bahasa kueri seperti SQL untuk melakukan transformasi dan komputasi melalui aliran data peristiwa. Bahasa ini mencakup banyak fungsi bawaan, tetapi beberapa skenario kompleks membutuhkan fleksibilitas lebih. Dengan menggunakan fungsi pengguna .NET Standard (UDF), Anda dapat memanggil fungsi Anda sendiri yang ditulis dalam bahasa .NET Standard apa pun (misalnya, C# atau F#) untuk memperluas bahasa kueri Stream Analytics. Gunakan UDF untuk melakukan perhitungan matematika kompleks, impor model ML kustom menggunakan ML.NET, dan gunakan logika imputasi khusus untuk data yang hilang.

Karena fitur ini sudah tidak digunakan, gunakan artikel ini untuk memahami cara kerja .NET Standard UDF dan merencanakan migrasi Anda ke fungsi yang didefinisikan pengguna JavaScript.

Tentang fungsi yang ditentukan pengguna .NET Standard

.NET Standard UDF memperluas bahasa kueri Stream Analytics dengan logika kustom. Sebelum Anda membangun UDF, tinjau wilayah tempat fitur dijalankan, jalur paket yang digunakan, pemetaan tipe yang didukung, dan batasan fitur.

Azure Stream Analytics mengaktifkan fitur fungsi .NET yang didefinisikan pengguna untuk pekerjaan cloud yang berjalan di klaster Stream Analytics. Pekerjaan yang berjalan di Standard multitenant SKU dapat menggunakan fitur ini di wilayah publik berikut:

Barat Sentral AS
Eropa Utara
US Timur
US Barat
US Timur 2
Eropa Barat

Untuk menggunakan fitur ini di wilayah lain, minta akses.

Format paket UDF apa pun memiliki jalur /UserCustomCode/CLR/*. Azure Stream Analytics menyalin pustaka tautan dinamis (DLL) dan sumber daya ke dalam folder /UserCustomCode/CLR/*, yang membantu mengisolasi DLL pengguna dari DLL sistem dan DLL Azure Stream Analytics. Semua fungsi menggunakan jalur paket ini, terlepas dari bagaimana Anda menggunakannya.

Agar nilai Azure Stream Analytics digunakan di C#, nilai tersebut perlu dinaungi dari satu lingkungan ke lingkungan lainnya. Marshaling terjadi untuk semua parameter input UDF. Setiap tipe Azure Stream Analytics memiliki tipe yang sesuai dalam C#, yang ditunjukkan pada tabel berikut:

Azure Stream Analytics tipe	Tipe C#
bigint	long
float	dua kali lipat
nvarchar(maks)	string
tanggalwaktu	DateTime
Rekaman	String kamus<, objek>
Array	Objek[]

Hal yang sama berlaku ketika data perlu dipindahkan dari C# ke Azure Stream Analytics, yang terjadi pada saat pengolahan nilai output UDF. Tabel berikut menunjukkan tipe yang didukung:

tipe C#	Jenis Azure Stream Analytics
long	bigint
dua kali lipat	float
string	nvarchar(maks)
DateTime	tanggalWaktu
struct	Rekaman
objek	Rekaman
Objek[]	Array
String kamus<, objek>	Rekaman

Fitur UDF memiliki keterbatasan sebagai berikut:

Anda hanya dapat membuat .NET Standard UDF di Visual Studio Code atau Visual Studio, lalu mempublikasikannya ke Azure. Anda dapat melihat versi baca-saja dari UDF .NET Standard pada menu Fungsi di portal Azure. Portal Azure tidak mendukung pembuatan fungsi .NET Standard.
Editor kueri portal Azure menunjukkan kesalahan saat Anda menggunakan .NET Standard UDF di portal.
Anda tidak bisa memanggil endpoint REST eksternal, seperti melakukan pencarian IP terbalik atau mengambil data referensi dari sumber eksternal.
Karena kode kustom berbagi konteks dengan mesin Azure Stream Analytics, kode kustom tidak dapat merujuk apa pun yang memiliki namespace atau nama DLL yang bertentangan dengan kode Azure Stream Analytics. Misalnya, Anda tidak bisa merujuk Newtonsoft.Json.
Azure Stream Analytics menyalin file pendukung dalam proyek ke file zip User Custom Code yang digunakan saat Anda mempublikasikan pekerjaan ke cloud. Selama dekompresi, semua file dalam subfolder dipindahkan ke root folder User Custom Code di cloud. Dekompresi membuat file zip menjadi rata.
Kode Kustom Pengguna tidak mendukung folder kosong. Jangan tambahkan folder kosong ke file pendukung dalam proyek.

Mengembangkan UDF di Visual Studio Code

Alat Visual Studio Code untuk Azure Stream Analytics memudahkan Anda menulis UDF, menguji pekerjaan Anda secara lokal (bahkan offline), dan menerbitkan pekerjaan Azure Stream Analytics Anda ke Azure. Anda dapat mengimplementasikan .NET Standard UDF di Visual Studio Code dari proyek lokal atau dari DLL lokal. Anda juga dapat mereferensikan DLL lokal yang menyertakan fungsi yang ditentukan pengguna.

Gunakan proyek lokal untuk fungsi kompleks yang membutuhkan kekuatan penuh dari bahasa .NET Standard di luar bahasa ekspresinya, seperti logika prosedural atau rekursi. Proyek lokal juga membantu ketika Anda perlu membagikan logika fungsi di beberapa query Azure Stream Analytics, dan Anda dapat melakukan debug serta menguji fungsi Anda secara lokal. Dalam contoh berikut, CSharpUDFProject adalah proyek pustaka kelas C#, dan ASAUDFDemo adalah proyek Azure Stream Analytics, yang merujuk pada CSharpUDFProject.

Buat pustaka kelas .NET Standard baru di mesin lokal Anda.
Tulis kode di kelas Anda. Definisikan kelas sebagai publik dan objek sebagai publik statis. UDF berikut mengalikan bilangan bulat dengan dirinya sendiri untuk menghasilkan kuadrat dari bilangan bulat.
```
using System;

namespace CSharpUDFProject
{
   //
    public class Class1
    {
        public static Int64 SquareFunction(Int64 a)
        {
            return a * a;
        }
    }
}
```
Tambahkan file konfigurasi fungsi C# baru di proyek Azure Stream Analytics Anda, dan referensikan proyek perpustakaan kelas C#. Untuk menambahkan fungsi, pilih dan tahan (atau klik kanan) folder Functions , lalu pilih Add Item.
Tambahkan fungsi C# SquareFunction ke proyek Azure Stream Analytics Anda.
Masukkan nama fungsi C#.
Pada konfigurasi fungsi C#, pilih Pilih jalur proyek pustaka untuk memilih proyek C# Anda dari daftar dropdown, lalu pilih Bangun proyek untuk membangun proyek Anda. Lalu pilih Pilih kelas dan Pilih metode untuk memilih kelas terkait dan nama metode dari daftar dropdown. Untuk merujuk pada metode, tipe, dan fungsi dalam kueri Stream Analytics, definisikan kelas sebagai publik dan objek sebagai publik statis.
Untuk menggunakan C# UDF dari DLL sebagai gantinya, pilih Pilih path dll perpustakaan untuk memilih DLL, lalu pilih Select class dan Select method.

Panggil UDF di kueri Azure Stream Analytics Anda.

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

Konfigurasikan jalur assembly di JobConfig.json file konfigurasi pekerjaan, di bagian CustomCodeStorage . Langkah ini tidak diperlukan untuk pengujian lokal.
Sebelum mengirimkan pekerjaan ke Azure, konfigurasikan jalur paket di JobConfig.json file konfigurasi pekerjaan, di bagian CustomCodeStorage. Gunakan Select from your subscription di CodeLens untuk memilih langganan Anda, lalu pilih akun penyimpanan dan nama kontainer dari daftar tarik-turun. Biarkan Jalur sebagai default. Langkah ini tidak diperlukan untuk pengujian lokal.

Mengembangkan UDF di Visual Studio

Anda dapat mengimplementasikan UDF di Visual Studio dengan menggunakan file CodeBehind dalam proyek ASA, UDF dari proyek lokal, atau paket yang sudah ada dari akun penyimpanan Azure. Dalam contoh berikut, UDFTest adalah proyek perpustakaan kelas C#, dan ASAUDFDemo adalah proyek Azure Stream Analytics, yang merujuk pada UDFTest.

Untuk opsi CodeBehind, tulis fungsi yang ditentukan pengguna di file Script.asql CodeBehind. Alat Visual Studio secara otomatis mengompilasi file CodeBehind menjadi file assembly. Alat-alat ini mengemas assembly tersebut sebagai file zip dan mengunggahnya ke akun penyimpanan Anda saat Anda mengirimkan pekerjaan ke Azure. Untuk mempelajari cara menulis C# UDF menggunakan CodeBehind, ikuti tutorial C# UDF untuk pekerjaan Stream Analytics Edge.

Buat pustaka kelas .NET Standard baru di solusi Anda.
Tulis kode di kelas Anda. Definisikan kelas sebagai publik dan objek sebagai publik statis.
Bangun proyek Anda. Alat ini mengemas semua artefak di folder bin ke dalam file zip dan mengunggah file zip ke akun penyimpanan. Untuk referensi eksternal, gunakan referensi assembly sebagai pengganti paket NuGet.
Referensikan kelas baru di proyek Azure Stream Analytics Anda.
Tambahkan fungsi baru di proyek Azure Stream Analytics Anda.
Konfigurasikan jalur assembly dalam file konfigurasi job JobConfig.json. Atur jalur assembly ke Local Project Reference atau CodeBehind.
Bangun kembali proyek fungsi dan proyek Azure Stream Analytics.
Bangun proyek C# Anda agar Anda dapat menambahkan referensi ke UDF C# dari kueri Azure Stream Analytics.
Tambahkan referensi ke proyek C# di proyek ASA. Pilih dan tahan (atau klik kanan) node Referensi, lalu pilih Tambah Referensi.
Pilih nama proyek C# dari daftar.
Pastikan UDFTest muncul di bawah Referensi di Penjelajah Solusi.
Pilih dan tahan (atau klik kanan) folder Fungsi , lalu pilih Item Baru.
Tambahkan fungsi C# SquareFunction.json ke proyek Azure Stream Analytics Anda.
Buka fungsi di Penjelajah Solusi untuk menampilkan dialog konfigurasi.
Dalam konfigurasi fungsi C#, pilih Muat dari Referensi Proyek ASA dan nama rakitan, kelas, dan metode terkait dari daftar dropdown. Untuk merujuk pada metode, tipe, dan fungsi dalam kueri Stream Analytics, definisikan kelas sebagai publik dan objek sebagai publik statis.

Konfigurasikan paket UDF Standar .NET yang sudah ada

Anda dapat membuat .NET Standard UDF di IDE apa pun dan memanggilnya dari kueri Azure Stream Analytics Anda. Setelah Anda mengunggah paket zip assembly ke akun penyimpanan Azure Anda, Anda dapat menggunakan fungsi dalam kueri Azure Stream Analytics dengan menyertakan informasi penyimpanan dalam konfigurasi pekerjaan Stream Analytics. Anda tidak dapat menguji fungsi secara lokal dengan opsi ini karena alat Visual Studio tidak mengunduh paket Anda. Layanan ini mengurai jalur paket secara langsung. Untuk menggunakan paket yang sudah ada:

Kompilasi kode Anda dan kemas semua DLL dengan menggunakan path /UserCustomCode/CLR/*.
Unggah UserCustomCode.zip ke root kontainer di akun penyimpanan Azure Anda.
Dalam file konfigurasi job JobConfig.json, perluas bagian Konfigurasi Kode Buatan Pengguna.

Isi konfigurasi dengan nilai yang disarankan berikut.

Setting	Nilai yang disarankan
Sumber Daya Pengaturan Penyimpanan Global	Pilih sumber data dari akun saat ini
Langganan Pengaturan Penyimpanan Global	< langganan Anda >
Pengaturan Penyimpanan Global Akun Penyimpanan	< akun penyimpanan Anda >
Sumber Daya Pengaturan Penyimpanan Kode Kustom	Pilih sumber data dari akun saat ini
Pengaturan Penyimpanan Akun Penyimpanan Kode Kustom	< akun penyimpanan Anda >
Wadah Pengaturan Penyimpanan Kode Kustom	< kontainer penyimpanan Anda >
Sumber Rakitan Kode Kustom	Paket perakitan yang ada dari cloud
Sumber Rakitan Kode Kustom	UserCustomCode.zip

Catat informasi kustom dengan kelas StreamingContext

Dengan menggunakan mekanisme pencatatan, Anda dapat menangkap informasi khusus saat pekerjaan berjalan. Gunakan data log untuk melakukan debug atau menilai kebenaran kode kustom secara real time. Gunakan langkah-langkah berikut untuk mempublikasikan dan mengakses pesan log:

Gunakan StreamingContext kelas untuk mempublikasikan informasi diagnostik menggunakan StreamingDiagnostics.WriteError fungsi. Kode berikut menunjukkan antarmuka yang diekspos oleh Azure Stream Analytics.

public abstract class StreamingContext
{
    public abstract StreamingDiagnostics Diagnostics { get; }
}

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

Lewatkan StreamingContext sebagai parameter input ke metode UDF, dan gunakan di dalam UDF untuk mempublikasikan informasi log kustom. Dalam contoh berikut, MyUdfMethod mendefinisikan input data yang disediakan oleh query, dan input konteks sebagai StreamingContext, yang disediakan oleh mesin runtime.
```
public static long MyUdfMethod(long data, StreamingContext context)
{
    // write log
    context.Diagnostics.WriteError("User Log", "This is a log message");

    return data;
}
```
Hubungi UDF dari pertanyaan Anda. Anda tidak perlu memasukkan StreamingContext nilai tersebut dalam kueri SQL, karena Azure Stream Analytics secara otomatis menyediakan objek konteks jika ada parameter input. Penggunaan MyUdfMethod tidak berubah, seperti yang ditunjukkan dalam kueri berikut.
```
SELECT udf.MyUdfMethod(input.value) as udfValue FROM input
```
Akses pesan log melalui log diagnostik.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-08-27