開發適用於 Azure 串流分析作業的 .NET Standard 使用者定義函式（已淘汰）

這很重要

.NET Standard 的 Azure 串流分析用戶定義函式已於 2024 年 9 月 30 日退役。此功能現已不再提供。轉用JavaScript user-defined functions來管理Azure 串流分析。

Azure 串流分析提供類似 SQL 的查詢語言，用於對事件資料流進行轉換與計算。該語言包含許多內建函式，但某些複雜情境需要更多彈性。透過使用 .NET Standard 使用者定義函式（UDF），你可以呼叫用任何 .NET Standard 語言（例如 C# 或 F#）撰寫的函式，來擴充 Stream Analytics 查詢語言。使用 UDF 進行複雜的數學運算，透過 ML.NET 匯入自訂機器學習模型，並對缺失資料使用自訂補實邏輯。

由於此功能已退休，請利用本文了解 .NET 標準 UDF 的運作方式，並規劃遷移至 JavaScript 使用者自訂函式的過程。

關於 .NET 標準使用者定義函式

.NET 標準 UDF 以自訂邏輯擴充串流分析查詢語言。在建立 UDF 之前，先檢視該功能執行的區域、它所使用的套件路徑、支援的型別映射以及功能限制。

Azure 串流分析啟用了 .NET 使用者定義函式功能，適用於在 Stream Analytics 叢集上執行的雲端工作。在標準多租戶 SKU 上執行的工作可在以下公開區域使用此功能：

美國中西部
北歐
美國東部
美國西部
美國東部 2
西歐

若要在其他地區使用此功能，請申請存取權限。

任何 UDF 封包的格式皆有路徑 /UserCustomCode/CLR/*。 Azure 串流分析會將動態連結函式庫（DLL）和資源複製到資料夾下方/UserCustomCode/CLR/*，幫助使用者將 DLL 與系統及 Azure 串流分析的 DLL 隔離開來。所有函式都會使用這個套件路徑，無論你怎麼使用它們。

要在 C# 中使用 Azure 串流分析的值，必須從一個環境封送到另一個環境。封組處理是針對 UDF 的所有輸入參數進行的。每個 Azure 串流分析類型在 C# 中都有對應的類型，如下表所示：

Azure 串流分析類型	C# 型別
Bigint	long
float	double
nvarchar(max)	字串
日期時間	DateTime
錄製	字典<字串，物件>
Array	對象[]

當需要將資料從 C# 編組傳送到 Azure 串流分析時，情況也是如此，而這通常發生在 UDF 的輸出值上。下表顯示了支援的類型：

C# 型別	Azure 串流分析類型
long	Bigint
double	float
字串	nvarchar(max)
DateTime	dateTime
結構	錄製
物件	錄製
對象[]	Array
字典<字串，物件>	錄製

UDF 功能有以下限制：

你只能在 Visual Studio Code 或 Visual Studio 中撰寫 .NET Standard UDF，然後發佈到 Azure。你可以在 Azure 入口網站的函式中查看唯讀版本的 .NET 標準 UDF。 Azure 入口網站不支援撰寫 .NET Standard 函式。
當你在入口網站使用 .NET Standard UDF 時，Azure 入口網站查詢編輯器會顯示錯誤。
你無法呼叫外部 REST 端點，例如做反向 IP 查詢或從外部來源拉取參考資料。
因為自訂程式碼與 Azure 串流分析引擎共享上下文，自訂程式碼無法引用與 Azure 串流分析程式碼在命名空間或 DLL 名稱衝突的物件。例如，你不能引用 Newtonsoft.Json。
Azure 串流分析會將專案中的支援檔案複製到它發布作業到雲端時使用的使用者自訂程式碼壓縮檔。解壓時，子資料夾中的所有檔案會移至雲端使用者自訂程式碼資料夾的根目錄。解壓會把壓縮檔壓扁。
使用者自訂程式碼不支援空資料夾。不要在專案中的支援檔案中新增空資料夾。

在 Visual Studio Code 中開發 UDF

Azure Stream Analytics 的 Visual Studio Code 工具讓你可以輕鬆撰寫 UDF、在本地（甚至離線）測試你的工作，並將你的 Stream Analytics 工作發佈到 Azure。你可以在 Visual Studio Code 中，從本機專案或本機 DLL 實作 .NET Standard UDF。你也可以參考包含使用者自訂函式的本地 DLL。

對於需要超越其表達式語言之 .NET Standard 語言完整功能的複雜函式 (例如程序性邏輯或遞迴)，請使用本機專案。本機專案也有助於您在多個 Azure 串流分析查詢之間共用函式邏輯，並可在本機對函式進行偵錯和測試。以下範例中，CSharpUDFProject 是一個 C# 類別函式庫專案，而 ASAUDFDemo 是 Azure 串流分析專案，該專案參考了 CSharpUDFProject。

在你的本機上建立一個新的 .NET Standard 類別函式庫。

在你的類別中寫程式碼。將類別定義為 public ，物件定義為 靜態 public。下列 UDF 會將整數乘以其本身，產生該整數的平方。

using System;

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

在你的 Azure 串流分析專案中新增一個新的 C# 函式設定檔，並參考 C# 類別庫專案。要新增函式，請選擇並長按（或右鍵點擊） Functions 資料夾，然後選擇 新增項目。
在您的 Azure 串流分析專案中新增 C# 函式 SquareFunction 。
輸入 C# 函式名稱。
在 C# 函式設定中，選擇 選擇函式庫專案路徑 ，從下拉選單中選擇你的 C# 專案，然後選擇 建置專案 來建立你的專案。接著選擇 「選擇類別 」和 「選擇方法 」，從下拉選單中選擇相關的類別和方法名稱。要參考 Stream Analytics 查詢中的方法、型別與函式，將類別定義為 public ，物件定義為 靜態 public。
若要改用 DLL 的 C# UDF，請選擇「 選擇函式庫 dll 路徑 」以選擇 DLL，然後選擇 「選擇類別 」和 「選擇方法」。

在你的 Azure 串流分析查詢中調用 UDF。

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

在作業設定檔的 JobConfig.json 區段中設定組件路徑。此步驟在局部檢測中不需。
在提交工作到 Azure 之前，請先JobConfig.json在工作設定檔的 CustomCodeStorage 區段設定套件路徑。在 CodeLens 裡用「 從訂閱中選擇 」來選擇你的訂閱，然後從下拉選單中選擇儲存帳號和容器名稱。讓路徑保持預設。此步驟在局部檢測中不需。

在 Visual Studio 中開發 UDF

你可以在 Visual Studio 中實作 UDF，方法是在 ASA 專案中使用 CodeBehind 檔案、本地專案的 UDF，或是 Azure 儲存帳號的現有套件。以下範例中，UDFTest 是一個 C# 類別函式庫專案，而 ASAUDFDemo 是 Azure 串流分析專案，該專案參考了 UDFTest。

針對 CodeBehind 選項，請在 Script.asql CodeBehind 檔案中撰寫使用者自訂函式。 Visual Studio 工具會自動將 CodeBehind 檔案編譯成組合檔。這些工具會把組裝檔打包成壓縮檔，並在你提交工作到 Azure 時上傳到你的儲存帳號。想學習如何使用 CodeBehind 撰寫 C# UDF，請參考 C# UDF for Stream Analytics Edge 工作教學。

在你的解決方案中建立一個新的 .NET Standard 類別函式庫。
在你的類別中寫程式碼。將類別定義為 public ，物件定義為 靜態 public。
建立您的專案。這些工具會把 bin 資料夾裡的所有 artifacts 打包成 zip 檔，然後把 zip 檔上傳到儲存帳號。對於外部參考，請使用組件參考，而非 NuGet 套件。
在你的 Azure 串流分析專案中引用這個新類別。
在您的 Azure 串流分析專案中新增一個函式。
在 JobConfig.json 作業設定檔中設定組件路徑。將組裝路徑設為 Local Project Reference 或 CodeBehind。
重建函式專案和 Azure 串流分析專案。
建立你的 C# 專案，這樣你就能從 Azure 串流分析查詢中新增 C# UDF 的參考。
在 ASA 專案中加入對 C# 專案的參考。選擇並長按（或右鍵點擊）參考節點，然後選擇 新增參考。
從列表中選擇 C# 專案名稱。
確認 UDFTest 是否出現在 方案總管 的參考資料中。
選取並長按（或右鍵點擊 ）功能資料夾 ，然後選擇 新項目。
在你的 Azure 串流分析專案中新增 C# 函式 SquareFunction.json 。
在 方案總管 開啟該功能以顯示設定對話框。
在 C# 函式設定中，從 ASA 專案參考中選擇載入 ，並從下拉選單中選擇相關的組合語言、類別和方法名稱。要參考 Stream Analytics 查詢中的方法、型別與函式，將類別定義為 public ，物件定義為 靜態 public。

配置現有的 .NET 標準 UDF 套件

你可以在任何 IDE 中撰寫 .NET Standard UDF，並從 Azure 串流分析查詢中調用它們。當你將組合套件壓縮包上傳到 Azure 儲存帳號後，你可以在 Azure 串流分析查詢中使用這些功能，方法是將儲存資訊納入 Stream Analytics 的工作設定中。你無法用這個選項在本地測試函式，因為 Visual Studio 工具不會下載你的套件。服務會直接解析套件路徑。若要使用現有套件：

編譯你的程式碼並用路徑 /UserCustomCode/CLR/*打包所有 DLL。
上傳UserCustomCode.zip到你 Azure 儲存帳號容器的根目錄。
在 JobConfig.json 作業設定檔中，展開 使用者定義程式碼設定 區段。

請使用以下建議值填寫設定。

Setting	建議的值
全域儲存體設定資源	從目前帳戶選擇資料來源
全域儲存設定訂閱	< 您的訂閱 >
全域儲存設定的儲存體帳戶	< 您的儲存體帳戶 >
自訂程式碼儲存設定資源	從目前帳戶選擇資料來源
自訂程式碼儲存設置的儲存帳戶	< 您的儲存體帳戶 >
自訂程式碼儲存設定容器	< 您的儲存容器 >
自訂程式碼組合原始碼	來自雲端的現有組合套件
自訂程式碼組合原始碼	UserCustomCode.zip

使用 StreamingContext 類別記錄自訂資訊

透過日誌機制，你可以在工作執行時擷取自訂資訊。利用日誌資料即時除錯或評估自訂程式碼的正確性。請依照以下步驟發布並存取日誌訊息：

使用 StreamingContext 類別，透過 StreamingDiagnostics.WriteError 函式發佈診斷資訊。以下程式碼顯示 Azure 串流分析所提供的介面。

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

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

將輸入參數傳遞 StreamingContext 給 UDF 方法，並在 UDF 內使用它來發布自訂日誌資訊。在下列範例中，MyUdfMethod 定義了由查詢所提供的資料輸入，以及做為 StreamingContext (由執行階段引擎所提供) 的內容輸入。
```
public static long MyUdfMethod(long data, StreamingContext context)
{
    // write log
    context.Diagnostics.WriteError("User Log", "This is a log message");

    return data;
}
```
從查詢中呼叫 UDF。你不需要在 SQL 查詢中傳遞該StreamingContext值，因為 Azure 串流分析會自動提供上下文物件，只要有輸入參數存在。如以下查詢所示，該 MyUdfMethod 詞的用法並未改變。
```
SELECT udf.MyUdfMethod(input.value) as udfValue FROM input
```
透過診斷日誌存取日誌訊息。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-01