Azure Stream Analytics 작업에 대한 .NET Standard 사용자 정의 함수 개발(사용 중지됨)

중요합니다

Azure Stream Analytics용 .NET Standard 사용자 정의 함수는 2024년 9월 30일에 사용 중지되었습니다. 이 기능은 더 이상 제공되지 않습니다. Azure Stream Analytics에서 JavaScript 사용자 정의 함수로 전환하세요.

Azure Stream Analytics는 이벤트 데이터 스트림을 통해 변환 및 계산을 수행하기 위한 SQL과 유사한 쿼리 언어를 제공합니다. 이 언어는 많은 내장 함수를 포함하고 있지만, 일부 복잡한 상황에서는 더 많은 유연성이 필요합니다. .NET Standard 사용자 정의 함수(UDF)를 사용하면 .NET 표준 언어(예: C#, F#)로 작성된 자체 함수를 호출하여 스트림 애널리틱스 쿼리 언어를 확장할 수 있습니다. UDF를 사용해 복잡한 수학 계산을 수행하고, ML.NET를 이용해 맞춤형 ML 모델을 가져오며, 누락된 데이터에 대해 맞춤형 보철 논리를 사용할 수 있습니다.

이 기능이 폐지되었기 때문에, 이 글을 활용해 .NET 표준 UDF가 어떻게 작동하는지 이해하고 JavaScript 사용자 정의 함수로의 이전 계획을 세우세요.

.NET 표준 사용자 정의 함수 소개

.NET 표준 UDF는 스트림 분석 쿼리 언어를 맞춤형 로직으로 확장합니다. UDF를 만들기 전에 해당 기능이 실행되는 영역, 사용하는 패키지 경로, 지원되는 타입 매핑, 그리고 기능 제한 사항을 검토하세요.

Azure Stream Analytics는 Stream Analytics 클러스터에서 실행되는 클라우드 작업에 대해 .NET 사용자 정의 함수 기능을 활성화합니다. 표준 다중 테넌트 SKU에서 실행되는 작업은 다음 공개 영역에서 이 기능을 사용할 수 있습니다:

미국 중서부
북유럽
East US
West US
미국 동부 2
West Europe

다른 지역에서 이 기능을 사용하려면 접근 권한을 요청하세요.

UDF 패키지의 형식에는 경로 /UserCustomCode/CLR/*가 있습니다. Azure Stream Analytics는 폴더 아래에 /UserCustomCode/CLR/* 동적 링크 라이브러리(DLL)와 리소스를 복사하여 사용자 DLL을 시스템 및 Azure Stream Analytics DLL과 분리하는 데 도움을 줍니다. 모든 함수는 어떻게 사용하든 이 패키지 경로를 사용합니다.

C#에서 Azure Stream Analytics 값을 사용하려면 한 환경에서 다른 환경으로 마샬링해야 합니다. 마샬링이 UDF의 모든 입력 매개 변수에 대해 발생합니다. 모든 Azure Stream Analytics 유형은 다음 표에 나타나는 C#에 대응하는 유형이 있습니다:

Azure Stream Analytics 유형	C# 형식
빅인트 (bigint)	long
떠다니다	double
nvarchar(max)	문자열
datetime	DateTime
녹음	<사전 문자열, 개체>
Array	Object[]

데이터를 C#에서 Azure Stream Analytics로 마샬링해야 하는 경우에도 마찬가지입니다. 이는 UDF의 출력 값에서 발생합니다. 다음 표는 지원되는 유형을 보여줍니다:

C# 형식	Azure Stream Analytics 유형
long	빅인트 (bigint)
double	떠다니다
문자열	nvarchar(max)
DateTime	dateTime
struct	녹음
객체	녹음
Object[]	Array
<사전 문자열, 개체>	녹음

UDF 기능에는 다음과 같은 제한이 있습니다:

.NET 표준 UDF는 Visual Studio Code 또는 Visual Studio에서만 작성할 수 있고, 이를 Azure에 게시할 수 있습니다. Azure 포털의 Functions에서 읽기 전용 버전의 .NET Standard UDF를 볼 수 있습니다. Azure 포털은 .NET Standard 함수 작성을 지원하지 않습니다.
Azure 포털 쿼리 편집기에서 .NET Standard UDF를 사용할 때 오류가 발생합니다.
리버스 IP 조회나 외부 출처에서 참조 데이터를 가져오는 등 외부 REST 엔드포인트에 호출할 수 없습니다.
커스텀 코드는 Azure Stream Analytics 엔진과 컨텍스트를 공유하기 때문에, 커스텀 코드는 Azure Stream Analytics 코드와 충돌하는 네임스페이스나 DLL 이름을 가진 어떤 것도 참조할 수 없습니다. 예를 들어, Newtonsoft.Json을 참조할 수 없습니다.
Azure Stream Analytics는 프로젝트 내 지원 파일을 사용자 사용자 지정 코드 zip 파일로 복사하여 작업을 클라우드에 게시할 때 사용합니다. 압축 해제 과정에서 하위 폴더의 모든 파일은 클라우드 내 사용자 사용자 맞춤 코드 폴더의 루트로 이동합니다. 압축 해제는 압축 파일을 평평하게 만듭니다.
사용자 지정 코드는 빈 폴더를 지원하지 않습니다. 프로젝트의 지원 파일에 빈 폴더를 추가하지 마세요.

Visual Studio Code에서 UDF 개발

Azure Stream Analytics용 Visual Studio Code 도구를 사용하면 UDF를 쉽게 작성하고, 로컬에서(오프라인으로도) 작업을 테스트하고, Stream Analytics 작업을 Azure에 게시할 수 있습니다. 로컬 프로젝트나 로컬 DLL에서 .NET 표준 UDF를 Visual Studio Code에 구현할 수 있습니다. 사용자 정의 함수를 포함하는 로컬 DLL을 참조할 수도 있습니다.

절차적 논리나 재귀처럼 표현 언어를 넘어 .NET 표준 언어의 전력을 모두 필요로 하는 복잡한 함수에는 로컬 프로젝트를 사용하세요. 로컬 프로젝트는 여러 Azure Stream Analytics 쿼리에서 함수 로직을 공유할 때 유용하며, 로컬에서 디버깅과 테스트를 할 수 있습니다. 다음 예시에서 CSharpUDFProject는 C# 클래스 라이브러리 프로젝트이고, ASAUDFDemo는 CSharpUDFProject를 참조하는 Azure Stream Analytics 프로젝트입니다.

로컬 머신에서 새로운 .NET Standard 클래스 라이브러리를 만드세요.

클래스에서 코드를 작성합니다. 클래스는 공개 로, 객체는 정적 공개로 정의하세요. 다음 UDF는 정수를 곱해 정수의 제곱을 만듭니다.

using System;

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

Azure Stream Analytics 프로젝트에 새로운 C# 함수 구성 파일을 추가하고, C# 클래스 라이브러리 프로젝트를 참조하세요. 함수를 추가하려면 Functions 폴더를 선택하고 길게 누르거나 우클릭한 후 Add Item을 선택하세요.
Azure Stream Analytics 프로젝트에 C# 함수 SquareFunction 을 추가합니다.
C# 함수 이름을 입력하세요.
C# 함수 구성에서 드롭다운 목록에서 C# 프로젝트를 선택하려면 라이브러리 프로젝트 경로를 선택하고, 프로젝트를 빌드하려면 프로젝트를 만듭니다. 그런 다음 클래스 선택 및 Select 메서드 를 선택하여 드롭다운 목록에서 관련 클래스 및 메서드 이름을 선택합니다. 스트림 분석 쿼리에서 메서드, 타입, 함수를 참조하기 위해, 클래스를 공개(public )로, 객체를 정적 공개(static public)로 정의하세요.
DLL에서 C# UDF를 사용하려면, 라이브러리 선택(Choose library dll path )을 선택해 DLL을 선택한 후, 클래스 선택 과 메서드를 선택하세요.

Azure Stream Analytics 쿼리에서 UDF를 호출합니다.

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

작업 구성 파일의 CustomCodeStorage 섹션에서 JobConfig.json 어셈블리 경로를 설정하세요. 이 단계는 국부 검사에는 필요하지 않습니다.
작업을 Azure에 제출하기 전에, 작업 구성 파일의 CustomCodeStorage 섹션에서 JobConfig.json 패키지 경로를 설정하세요. CodeLens에서 구독에서 선택(Select from your subscription )을 사용해 구독을 선택하고, 드롭다운 목록에서 저장 계정과 컨테이너 이름을 선택하세요. 경로를 기본값으로 둡니다. 이 단계는 국부 검사에는 필요하지 않습니다.

Visual Studio에서 UDF 개발

Visual Studio에서는 ASA 프로젝트의 CodeBehind 파일, 로컬 프로젝트의 UDF, Azure 스토리지 계정의 기존 패키지를 사용해 UDF를 구현할 수 있습니다. 다음 예시에서 UDFTest는 C# 클래스 라이브러리 프로젝트이고, ASAUDFDemo는 UDFTest를 참조하는 Azure Stream Analytics 프로젝트입니다.

CodeBehind 옵션의 경우, Script.asql CodeBehind 파일에 사용자 정의 함수를 작성하세요. Visual Studio 도구는 CodeBehind 파일을 자동으로 어셈블리 파일로 컴파일합니다. 도구들은 어셈블리를 zip 파일로 패키징하고, 작업을 Azure에 제출할 때 스토리지 계정에 업로드합니다. CodeBehind를 사용해 C# UDF 작성법을 배우고 싶다면, 스트림 애널리틱스 엣지 잡 튜토리얼을 위한 C# UDF 튜토리얼을 따라가세요.

솔루션 내에 새로운 .NET 표준 클래스 라이브러리를 만드세요.
클래스에서 코드를 작성합니다. 클래스는 공개 로, 객체는 정적 공개로 정의하세요.
프로젝트를 빌드합니다. 도구들은 bin 폴더 내 모든 아티팩트를 zip 파일로 패키징하고, zip 파일을 저장 계정에 업로드합니다. 외부 참조용으로는 NuGet 패키지 대신 어셈블리 참조를 사용하세요.
Azure Stream Analytics 프로젝트에서 새 클래스를 참조합니다.
Azure Stream Analytics 프로젝트에 새 함수를 추가합니다.
작업 구성 파일에서 JobConfig.json 어셈블리 경로를 설정하세요. 어셈블리 경로를 Local Project Reference 또는 CodeBehind로 설정하세요.
함수 프로젝트와 Azure Stream Analytics 프로젝트를 모두 다시 빌드합니다.
C# 프로젝트를 만들어서 Azure Stream Analytics 쿼리에서 C# UDF에 대한 참조를 추가할 수 있게 하세요.
ASA 프로젝트의 C# 프로젝트에 대한 참조를 추가합니다. 참조 노드를 선택하고 길게 누르거나 우클릭한 후, 참조 추가를 선택하세요.
목록에서 C# 프로젝트 이름을 선택합니다.
솔루션 탐색기의 참고문헌 항목에 UDFTest가 나타나는지 확인하세요.
Functions 폴더를 선택하고 길게 누르거나 우클릭한 후 새 항목을 선택하세요.
Azure Stream Analytics 프로젝트에 C# 함수 SquareFunction.json을 추가합니다.
솔루션 탐색기에서 해당 기능을 열어 구성 대화상자를 표시합니다.
C# 함수 구성의 드롭다운 목록에서 ASA 프로젝트 참조 및 관련 어셈블리, 클래스 및 메서드 이름에서 로드를 선택합니다. 스트림 분석 쿼리에서 메서드, 타입, 함수를 참조하기 위해, 클래스를 공개(public )로, 객체를 정적 공개(static public)로 정의하세요.

기존의 .NET 표준 UDF 패키지를 구성

어떤 IDE에서도 .NET Standard UDF를 작성하고 Azure Stream Analytics 쿼리에서 호출할 수 있습니다. 어셈블리 zip 패키지를 Azure 스토리지 계정에 업로드한 후, Stream Analytics 작업 구성에 저장 정보를 포함시켜 Azure Stream Analytics 쿼리의 기능을 사용할 수 있습니다. 이 옵션으로는 로컬에서 기능을 테스트할 수 없는데, Visual Studio 도구가 패키지를 다운로드하지 않기 때문입니다. 서비스는 패키지 경로를 직접 파싱합니다. 기존 패키지를 사용하는 방법:

코드를 컴파일하고 모든 DLL을 경로 를 사용하여 패키징하세요./UserCustomCode/CLR/*
UserCustomCode.zip를 Azure Storage 계정의 컨테이너 루트에 업로드하세요.
작업 JobConfig.json구성 파일에서 사용자 정의 코드 구성 섹션을 펼칩니다.

다음 제안된 값으로 구성을 작성하세요.

Setting	제안된 값
전역 스토리지 설정 리소스	현재 계정에서 데이터 원본 선택
전역 스토리지 설정 구독	< 구독 >
전역 스토리지 설정 스토리지 계정	< 스토리지 계정 >
사용자 지정 코드 스토리지 설정 리소스	현재 계정에서 데이터 원본 선택
사용자 지정 코드 스토리지 설정 스토리지 계정	< 스토리지 계정 >
사용자 지정 코드 스토리지 설정 컨테이너	< 사용자 스토리지 컨테이너 >
사용자 지정 코드 어셈블리 소스	클라우드의 기존 어셈블리 패키지
사용자 지정 코드 어셈블리 소스	UserCustomCode.zip

StreamingContext 클래스로 사용자 지정 정보를 기록하세요

로깅 메커니즘을 사용하면 작업이 실행되는 동안 사용자 정의 정보를 캡처할 수 있습니다. 로그 데이터를 활용해 실시간으로 맞춤 코드의 정확성을 디버깅하거나 평가하세요. 로그 메시지를 게시하고 접근하려면 다음 단계를 사용하세요:

StreamingDiagnostics.WriteError 함수를 사용하여 진단 정보를 게시하려면 StreamingContext 클래스를 사용하세요. 다음 코드는 Azure Stream Analytics가 제공하는 인터페이스를 보여줍니다.

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

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

UDF 메서드에 입력 매개변수로 전달 StreamingContext 하고, 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 Stream Analytics가 입력 매개변수가 있으면 자동으로 컨텍스트 객체를 제공하기 때문입니다. 다음 쿼리에서 보듯이 '의 MyUdfMethod 사용은 변하지 않습니다.'
```
SELECT udf.MyUdfMethod(input.value) as udfValue FROM input
```
진단 로그를 통해 로그 메시지에 접근하세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-08-27