你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

为 Azure 流分析作业开发 .NET Standard 用户定义函数(已停用)

重要

Azure 流分析 中的 .NET Standard 用户定义函数已于 2024 年 9 月 30 日停用。 该功能现已不再提供。 转用JavaScript用户定义函数用于Azure 流分析。

Azure 流分析提供类似于 SQL 的查询语言,用于对事件数据流执行转换和计算。 该语言包含许多内置函数,但某些复杂场景需要更多的灵活性。 通过使用 .NET 标准用户自定义函数(UDF),你可以调用用任何 .NET 标准语言(例如 C# 或 F#)编写的函数,以扩展 Stream Analytics 查询语言。 使用UDF进行复杂的数学计算,通过ML.NET导入自定义机器学习模型,并对缺失数据使用自定义补补逻辑。

由于该功能已被淘汰,请利用本文理解 .NET 标准 UDF 的工作原理,并规划迁移到 JavaScript 用户自定义函数的过程。

关于 .NET 标准用户自定义函数

.NET标准UDF通过自定义逻辑扩展了Stream Analytics查询语言。 在构建UDF之前,请审查该功能运行的区域、所使用的包路径、支持的类型映射以及功能限制。

Azure 流分析为运行在Stream Analytics集群上的云作业启用了.NET用户自定义函数功能。 运行在标准多租户 SKU 上的作业可以在以下公共区域使用此功能:

  • 美国中西部
  • 北欧
  • 美国东部
  • 美国西部
  • 美国东部 2
  • 西欧

要在其他地区使用此功能,请 请求访问权限。

任何 UDF 包的格式都有路径 /UserCustomCode/CLR/*。 Azure 流分析 会在文件夹下/UserCustomCode/CLR/*复制动态链接库(DLL)和资源,帮助用户将 DLL 与系统和 Azure 流分析 的 DLL 隔离开来。 所有函数都使用该包路径,无论你如何使用它们。

若要在 C# 中使用 Azure 流分析值,需要将其从一个环境封送到另一个环境。 对 UDF 的所有输入参数进行封送处理。 每个 Azure 流分析 类型在 C# 中都有对应的类型,如下表所示:

Azure 流分析 类型 C# 类型
bigint long
float double
nvarchar(max) 字符串
日期/时间 DateTime
记录 字典<字符串,对象>
Array Object[]

当需要将数据从 C# 封送到 Azure 流分析时也是如此,这发生在 UDF 的输出值上。 下表显示了支持的类型:

C# 类型 Azure 流分析 类型
long bigint
double float
字符串 nvarchar(max)
DateTime 日期时间
结构 记录
对象 记录
Object[] Array
字典<字符串,对象> 记录

UDF功能存在以下限制:

  • 你只能在 Visual Studio Code 或 Visual Studio 中编写 .NET 标准 UDF,然后发布到 Azure。 你可以在 Azure 门户的函数中查看 .NET 标准 UDF 的只读版本。 Azure 门户不支持编写 .NET Standard 函数。
  • 当你在门户中使用 .NET 标准 UDF 时,Azure 门户查询编辑器会显示错误。
  • 你不能调用外部 REST 端点,比如做反向 IP 查找或从外部来源获取参考数据。
  • 由于自定义代码与 Azure 流分析 引擎共享上下文,因此自定义代码无法引用任何命名空间或 DLL 名称与 Azure 流分析 代码冲突的内容。 比如,你不能引用 Newtonsoft.Json。
  • Azure 流分析 会将项目中的支持性文件复制到“用户自定义代码”zip 文件中,并在将作业发布到云时使用该文件。 解压期间,子文件夹中的所有文件都会迁移到云端用户自定义代码文件夹的根节点。 解压会把压缩包压缩。
  • 用户自定义代码不支持空文件夹。 不要将空文件夹添加到项目中的支持文件。

在 Visual Studio Code 中开发 UDF

使用适用于 Azure 流分析的 Visual Studio Code 工具 可以轻松编写 UDF、在本地测试作业(甚至脱机),并将流分析作业发布到 Azure。 你可以在本地项目或本地DLL中实现Visual Studio Code中的.NET标准UDF。 还可以引用包含用户定义的函数的本地 DLL。

对于需要使用超出其表达式语言范围的 .NET Standard 语言完整能力的复杂函数(例如过程逻辑或递归),请使用本地项目。 本地项目在需要在多个 Azure 流分析 查询中共享函数逻辑时也很有帮助,你可以在本地调试和测试你的函数。 在下面的例子中,CSharpUDFProject 是一个 C# 类库项目,ASAUDFDemo 是 Azure 流分析 项目,引用了 CSharpUDFProject。

  1. 在你的本地机器上创建一个新的 .NET Standard 类库。

    Visual Studio Code 中 Azure 流分析 项目的截图。

  2. 在类中编写代码。 将类定义为 公共 ,对象定义为 静态公共。 接下来的UDF将整数乘以自己,得到整数的平方。

    using System;
    
    namespace CSharpUDFProject
    {
       //
        public class Class1
        {
            public static Int64 SquareFunction(Int64 a)
            {
                return a * a;
            }
        }
    }
    
  3. 在你的 Azure 流分析 项目中添加一个新的 C# 函数配置文件,并引用 C# 类库项目。 要添加该函数,选择并长按(或右键点击 )功能文件夹 ,然后选择 添加项目。

    在 Azure 流分析 项目中添加新功能的截图。

  4. 将 C# 函数 SquareFunction 添加到 Azure 流分析项目。

    在VS Code中选择Stream Analytics项目中的C#函数截图。

  5. 输入 C# 函数名称。

    在 Visual Studio Code 中输入 C# 函数名称的截图。

  6. 在 C# 函数配置中,选择 选择库项目路径 ,从下拉列表中选择你的 C# 项目,然后选择 构建项目 来构建你的项目。 然后选择 “选择类 ”和 “选择方法” ,从下拉列表中选择相关类和方法名称。 在 Stream Analytics 查询中,要指代方法、类型和函数,将类定义为 public ,对象为 静态 public。

    VS Code 中 Stream Analytics C# 函数配置的截图。

  7. 要改用 DLL 中的 C# UDF,选择 Choose library dll 路径 以选择 DLL,然后选择 Select 类 和 Select 方法。

    库 DLL 的 Stream Analytics C# 函数配置截图。

  8. 在 Azure 流分析查询中调用 UDF。

     SELECT price, udf.SquareFunction(price)
     INTO Output
     FROM Input 
    
  9. 在 作业配置文件的 JobConfig.json 部分配置程序集路径。 本地检测不需要这一步。

  10. 在提交作业到Azure之前,请在作业配置文件的CustomCodeStorage部分配置包路径JobConfig.json。 在CodeLens中使用“ 从订阅中选择 ”来选择你的订阅,然后从下拉列表中选择存储账户和容器名称。 将 Path 保留为默认值。 本地检测不需要这一步。

    这是为Stream Analytics C#函数配置存储账户的截图。

在 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,请参阅 适用于流分析 Edge 作业的 C# UDF 教程。

  1. 在你的解决方案中创建一个新的 .NET Standard 类库。

    在 Visual Studio 中的 Azure 流分析 IoT Edge 项目的屏幕截图。

  2. 在类中编写代码。 将类定义为 公共 ,对象定义为 静态公共。

  3. 构建你的项目。 这些工具会把bin文件夹里的所有工件打包成一个压缩包,然后把压缩包上载到存储账户。 对于外部引用,使用汇编引用代替 NuGet 包。

  4. 引用 Azure 流分析项目中的新类。

  5. 在 Azure 流分析项目中添加新函数。

  6. 在 JobConfig.json 作业配置文件中配置装配路径。 将汇编路径设置为 Local Project Reference 或 CodeBehind。

  7. 重新生成函数项目和 Azure 流分析项目。

  8. 构建你的 C# 项目,这样你就能从 Azure 流分析 查询中添加对 C# UDF 的引用。

    在 Visual Studio 中构建 Azure 流分析 IoT Edge 项目的屏幕截图。

  9. 在 ASA 项目中添加对 C# 项目的引用。 选择并长按(或右键点击 )参考节点 ,然后选择 添加引用。

    在Visual Studio中添加C#项目引用的截图。

  10. 从列表中选择 C# 项目名称。

    从Visual Studio的参考列表中选择C#项目名称的截图。

  11. 确认UDFTest是否出现在解决方案资源管理器的参考文献中。

    Visual Studio 解决方案资源管理器 中用户自定义函数引用的截图。

  12. 选择并长按(或右键点击 )功能文件夹 ,然后选择 新项目。

    在 Azure 流分析 Edge 解决方案中向 Functions 添加新项目的截图。

  13. 将 C# 函数 SquareFunction.json 添加到 Azure 流分析项目。

    在 Visual Studio 中从 Stream Analytics Edge 项目中选择 C# 函数的截图。

  14. 在 解决方案资源管理器 中打开该功能以显示配置对话框。

    Visual Studio 中 C# 函数配置对话框的截图。

  15. 在 C# 函数配置中, 从 ASA 项目引用中选择“加载 ”,并从下拉列表中选择相关的程序集、类和方法名称。 在 Stream Analytics 查询中,要指代方法、类型和函数,将类定义为 public ,对象为 静态 public。

    Visual Studio中Stream Analytics C#函数配置的截图,带有ASA项目引用。

配置现有的.NET标准UDF包

你可以在任何IDE中编写.NET标准UDF文件,并从你的Azure 流分析查询中调用它们。 在你把汇编压缩包上传到Azure存储账户后,可以通过在Stream Analytics作业配置中包含存储信息,使用Azure 流分析查询中的这些功能。 你不能用这个选项在本地测试该函数,因为 Visual Studio 工具不会下载你的包。 服务直接解析包路径。 使用现有软件包:

  1. 编译你的代码,并用路径 /UserCustomCode/CLR/*打包所有 DLL。

  2. 将 UserCustomCode.zip 上传到你的 Azure 存储帐户中容器的根目录。

  3. 在 JobConfig.json 作业配置文件中,展开 用户定义代码配置 部分。

  4. 请使用以下建议值填写配置。

    设置 建议值
    全局存储设置资源 从当前帐户中选择数据源
    全局存储设置订阅服务 < 订阅 >
    全局存储设置存储帐户 < 您的存储帐户 >
    自定义代码存储设置资源 从当前帐户中选择数据源
    自定义代码存储设置存储帐户 < 您的存储帐户 >
    自定义代码存储配置容器 < 您的存储容器 >
    自定义代码程序集源 云中现有的组件包
    自定义代码程序集源 UserCustomCode.zip

使用 StreamingContext 类记录自定义信息

通过日志机制,你可以在作业运行时捕捉自定义信息。 使用日志数据实时调试或评估自定义代码的正确性。 请按照以下步骤发布和访问日志消息:

  1. 使用 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);
    }
    
  2. 将输入参数传递 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;
    }
    
  3. 在查询中调用 UDF。 你不需要在SQL查询中传递该StreamingContext值,因为如果有输入参数,Azure 流分析会自动提供上下文对象。 MyUdfMethod 的用法不变,如以下查询所示。

    SELECT udf.MyUdfMethod(input.value) as udfValue FROM input
    
  4. 通过诊断日志访问日志消息。