Разработка определяемых пользователем функций .NET Standard для заданий Azure Stream Analytics (предварительная версия)

Это важно

Определяемые пользователем функции .Net Standard для Azure Stream Analytics будут прекращены 30 сентября 2024 года. По истечении этой даты невозможно использовать эту функцию. Перейдите к определяемым пользователем функциям JavaScript для Azure Stream Analytics.

Azure Stream Analytics предлагает язык запросов, похожий на SQL, для выполнения преобразований и вычислений через потоки данных событий. Существует множество встроенных функций, но некоторые сложные сценарии требуют дополнительной гибкости. С помощью определяемых пользователем функций .NET Standard можно вызывать собственные функции, написанные на любом языке .NET standard (C#, F#, и т. д.), чтобы расширить язык запросов Stream Analytics. ФПП позволяют выполнять сложные математические вычисления, импортировать пользовательские модели машинного обучения с помощью ML.NET и использовать настраиваемую логику импутации для отсутствующих данных. Функция UDF для заданий Stream Analytics в настоящее время находится в предварительной версии и не должна использоваться в рабочих нагрузках.

Регионы

Функция пользовательских определений .NET включена для облачных задач, выполняемых в кластерах Stream Analytics. Задания, выполняемые в SKU стандартного уровня с мультитенантностью, могут использовать эту функцию в следующих публичных регионах:

Центрально-западная часть США
North Europe
Восток США
Западная часть США
Восток США 2
West Europe

Если вы хотите использовать эту функцию в любом другом регионе, вы можете запросить доступ.

Путь пакета

Формат любого пакета UDF имеет путь /UserCustomCode/CLR/*. Библиотеки динамических ссылок (DLL) и ресурсы копируются в папку /UserCustomCode/CLR/* , что помогает изолировать пользовательские библиотеки DLL из системных библиотек и библиотек DLL Azure Stream Analytics. Этот путь пакета используется для всех функций независимо от метода, используемого для их использования.

Поддерживаемые типы и сопоставление

Чтобы значения Azure Stream Analytics использовались в C#, их необходимо маршалировать из одной среды в другую. Маршалинг выполняется для всех входных параметров UDF. Каждый тип Azure Stream Analytics имеет соответствующий тип в C#, показанный в таблице ниже:

Тип Azure Stream Analytics	Тип C#
Бигинт	long
плавать	двойной
nvarchar(max)	струна
datetime	DateTime
Запись	словарь<строка, объект>
Массив	Объект[]

То же самое верно, если данные необходимо обрабатывать из C# в Azure Stream Analytics, что происходит на уровне выходного значения UDF. В таблице ниже показано, какие типы поддерживаются:

Тип C#	Тип Azure Stream Analytics
long	Бигинт
двойной	плавать
струна	nvarchar(max)
DateTime	дата и время
Структура	Запись
объект	Запись
Object[]	Массив
Строка словаря<, объект>	Запись

Разработка UDF в Visual Studio Code

Средства Visual Studio Code для Azure Stream Analytics упрощают создание пользовательских определяемых функций, тестирование заданий локально (даже в автономном режиме) и публикацию задания Stream Analytics в Azure.

Существует два способа реализации определяемых пользователем функций (UDF) стандарта .NET в средствах Visual Studio Code.

UDF из локальных библиотек DLL
UDF из локального проекта

Локальный проект

Определяемые пользователем функции можно записать в сборку, которая позже ссылается на запрос Azure Stream Analytics. Это рекомендуемый вариант для сложных функций, требующих полной мощности языка .NET Standard за пределами языка выражений, таких как процедурная логика или рекурсия. Определяемые пользователем функции из локального проекта также могут использоваться, когда требуется делиться логикой функции в нескольких запросах Azure Stream Analytics. Добавление определяемых пользователем функций в локальный проект позволяет выполнять отладку и тестирование этих функций локально.

Чтобы ссылаться на локальный проект, выполните указанные действия.

Создайте новую библиотеку классов .NET standard на локальном компьютере.
Напишите код в классе. Помните, что классы должны быть определены как общедоступные и объекты должны быть определены как статические общедоступные.
Добавьте новый файл конфигурации функции CSharp в проект Azure Stream Analytics и обратитесь к проекту библиотеки классов CSharp.
Настройте путь сборки в файле конфигурации задания, JobConfig.jsonраздел CustomCodeStorage . Этот шаг не нужен для локального тестирования.

Локальные библиотеки DLL

Вы также можете ссылаться на локальные библиотеки DLL, включающие определяемые пользователем функции.

Пример

В этом примере CSharpUDFProject — это проект библиотеки классов C#, а ASAUDFDemo — это проект Azure Stream Analytics, который будет ссылаться на CSharpUDFProject.

Проект Azure Stream Analytics в Visual Studio Code

Следующий UDF имеет функцию, которая умножает целое число самостоятельно для создания квадрата целого числа. Классы должны быть определены как общедоступные и объекты должны быть определены как статические общедоступные.

using System;

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

Ниже показано, как добавить функцию UDF C# в проект Stream Analytics.

Щелкните правой кнопкой мыши папку "Функции" и выберите пункт "Добавить элемент".
Добавьте функцию C# SquareFunction в проект Azure Stream Analytics.
В конфигурации функции C# выберите Выбрать путь к проекту библиотеки, чтобы выбрать ваш проект C# из раскрывающегося списка, и выберите Собрать проект, чтобы собрать ваш проект. Затем выберите класс Select и Select method , чтобы выбрать связанный класс и имя метода из раскрывающегося списка. Чтобы ссылаться на методы, типы и функции в запросе Stream Analytics, классы должны быть определены как общедоступные , а объекты должны быть определены как статические общедоступные.

Если вы хотите использовать UDF C# из библиотеки DLL, выберите путь к файлу библиотеки, чтобы выбрать библиотеку DLL. Затем выберите класс Select и Select method , чтобы выбрать связанный класс и имя метода из раскрывающегося списка.

Вызов UDF в запросе Azure Stream Analytics.

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

Перед отправкой задания в Azure настройте путь пакета в файле конфигурации задания, JobConfig.jsonраздел CustomCodeStorage . Используйте Выбрать из вашей подписки в CodeLens, чтобы выбрать вашу подписку, а затем из раскрывающегося списка выбрать учетную запись хранения и имя контейнера. Оставьте путь по умолчанию. Этот шаг не нужен для локального тестирования.

Разработка UDF в Visual Studio

Существует три способа реализации определяемых пользователем функций в средствах Visual Studio.

Файлы CodeBehind в проекте ASA
UDF из локального проекта
Существующий пакет из учетной записи хранения Azure

CodeBehind

Вы можете написать определяемые пользователем функции в Script.asql CodeBehind. Средства Visual Studio автоматически компилируют файл CodeBehind в файл сборки. Сборки упаковываются в виде ZIP-файла и отправляются в учетную запись хранения при отправке задания в Azure. Вы можете узнать, как написать UDF C# с помощью CodeBehind, следуя руководству по заданиям UDF C# для Stream Analytics Edge .

Локальный проект

Чтобы ссылаться на локальный проект в Visual Studio, выполните указанные действия.

Создание новой библиотеки классов .NET standard в решении
Напишите код в классе. Помните, что классы должны быть определены как общедоступные и объекты должны быть определены как статические общедоступные.
Создайте свой проект. Инструменты упакуют все артефакты в папке bin в zip-файл и отправят zip-файл в учетную запись хранения. Для внешних ссылок используйте ссылку на сборку вместо пакета NuGet.
Добавьте ссылку на новый класс в проекте Azure Stream Analytics.
Добавьте новую функцию в проект Azure Stream Analytics.
Настройте путь сборки в файле конфигурации задания. JobConfig.json Задайте путь сборки на Локальная ссылка на проект или CodeBehind.
Перестройте как проект функции, так и проект Azure Stream Analytics.

Пример

В этом примере UDFTest — это проект библиотеки классов C#, а ASAUDFDemo — это проект Azure Stream Analytics, который будет ссылаться на UDFTest.

Проект Azure Stream Analytics IoT Edge в Visual Studio

Создайте проект C#, который позволит добавить ссылку на UDF C# из запроса Azure Stream Analytics.
Добавьте ссылку на проект C# в проекте ASA. Щелкните правой кнопкой мыши узел "Ссылки" и выберите пункт "Добавить ссылку".
Выберите имя проекта C# в списке.
В обозревателе решений должна появиться функция UDFTest, указанная в разделе "Ссылки".
Щелкните правой кнопкой мыши папку "Функции " и выберите "Создать элемент".
Добавьте функцию C# SquareFunction.json в проект Azure Stream Analytics.
Дважды щелкните функцию в обозревателе решений , чтобы открыть диалоговое окно конфигурации.
В конфигурации функции C# выберите Load from ASA Project Reference и соответствующую сборку, класс и имена методов из раскрывающегося списка. Чтобы ссылаться на методы, типы и функции в запросе Stream Analytics, классы должны быть определены как общедоступные , а объекты должны быть определены как статические общедоступные.

Настройка функции Stream Analytics на C# в Visual Studio

Существующие пакеты

Вы можете создавать определяемые пользователем функции .NET Standard в любой интегрированной среде разработки (IDE) и затем вызывать их в запросах Azure Stream Analytics. Сначала скомпилируйте код и упаковайте все библиотеки DLL. Формат пакета имеет путь /UserCustomCode/CLR/*. Затем отправьте UserCustomCode.zip в корневой каталог контейнера в учетной записи хранения Azure.

После отправки zip-пакетов сборки в учетную запись хранения Azure можно использовать функции в запросах Azure Stream Analytics. Все, что необходимо сделать, — включить сведения о хранилище в конфигурацию задания Stream Analytics. Вы не можете локально протестировать функцию с помощью этого параметра, так как средства Visual Studio не будут загружать пакет. Путь к пакету анализируется непосредственно в службу.

Чтобы настроить путь сборки в файле конфигурации задания, выполните следующие действия: JobConfig.json

Разверните раздел конфигурации пользовательского кода и заполните его следующими значениями.

Настройки	Предлагаемое значение
Глобальный ресурс параметров хранилища	Выбор источника данных из текущей учетной записи
Подписка на глобальные настройки хранилища	< подписка >
Глобальные параметры хранения учетной записи хранения	< учетная запись хранения >
Ресурс параметров хранилища пользовательского кода	Выбор источника данных из текущей учетной записи
Учетная запись хранения пользовательских параметров хранилища кода	< учетная запись хранения >
Контейнер параметров хранилища пользовательского кода	< ваш контейнер для хранения >
Источник сборки пользовательского кода	Существующие пакеты сборок из облака
Источник сборки пользовательского кода	UserCustomCode.zip

Ведение журнала пользователей

Механизм ведения журнала позволяет записывать пользовательские сведения во время выполнения задания. Данные журнала можно использовать для отладки или оценки правильности пользовательского кода в режиме реального времени.

Класс StreamingContext позволяет публиковать диагностические сведения с помощью функции StreamingDiagnostics.WriteError. В приведенном ниже коде показан интерфейс, предоставляемый Azure Stream Analytics.

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;
}

Значение StreamingContext не требуется передавать в SQL-запросе. Azure Stream Analytics предоставляет объект контекста автоматически, если присутствует входной параметр. Использование MyUdfMethod не изменяется, как показано в следующем запросе.

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

Вы можете получить доступ к сообщениям журнала через журналы диагностики.

Ограничения

Предварительная версия UDF в настоящее время имеет следующие ограничения:

Функции, определяемые пользователем .NET Standard (UDF), можно создавать только в Visual Studio Code или Visual Studio и публиковать в Azure. Доступные только для чтения версии определяемых пользователем функций .NET Standard можно просмотреть в разделе Функции на портале Azure. Разработка функций .NET Standard не поддерживается на портале Azure.
В редакторе запросов портала Azure отображается ошибка при использовании UDF .NET Standard на портале.
Вызов внешних конечных точек REST, например при обратном поиске IP-адресов или извлечении ссылочных данных из внешнего источника
Поскольку пользовательский код совместно использует контекст с движком Azure Stream Analytics, пользовательский код не может ссылаться на что-либо, что имеет конфликтующее пространство имен или имя DLL с кодом Azure Stream Analytics. Например, нельзя ссылаться на Newtonsoft Json.
Вспомогательные файлы, включенные в проект, копируются в ZIP-файл пользовательского кода пользователя, который используется при публикации задания в облаке. Все файлы в вложенных папках копируются непосредственно в корень папки пользовательского кода в облаке при распаковке. Zip-файл "разворачивается" при распаковке.
Пользовательский код не поддерживает пустые папки. Не добавляйте пустые папки в вспомогательные файлы в проекте.

Дальнейшие шаги

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-26

Разработка определяемых пользователем функций .NET Standard для заданий Azure Stream Analytics (предварительная версия)

Регионы

Путь пакета

Поддерживаемые типы и сопоставление

Разработка UDF в Visual Studio Code

Локальный проект

Локальные библиотеки DLL

Пример

Разработка UDF в Visual Studio

CodeBehind

Локальный проект

Пример

Существующие пакеты

Ведение журнала пользователей

Ограничения

Дальнейшие шаги

Обратная связь

Дополнительные ресурсы