大网数据广告活动
Azure 网站与应用

WebJobs SDK 入门

· 52CE 我爱测

用于事件驱动的后台处理的 WebJobs SDK 简介。 了解如何访问 Azure 服务和第三方服务中的数据。

本文介绍如何使用 Visual Studio 2019 创建 Azure WebJobs SDK 项目、在本地运行它,然后将其部署到 Azure 应用服务。 WebJobs SDK 的 3.x 版同时支持 .NET Core 和 .NET Framework 控制台应用。 若要了解关于使用 WebJobs SDK 的详细信息,请参阅如何将 Azure WebJobs SDK 用于处理事件驱动的后台。

本文介绍如何将 WebJobs 部署为 .NET Core 控制台应用。 若要将 WebJobs 部署为 .NET Framework 控制台应用,请参阅 WebJobs 作为 .NET Framework 控制台应用。 如果你对仅支持 .NET Framework 的 WebJobs SDK 版本 2.x 感兴趣,请参阅使用 Visual Studio 开发和部署 WebJob - Azure 应用服务。

先决条件

  • 安装 Visual Studio 2019其中包含 Azure 开发工作负荷。 如果已安装 Visual Studio,但未配置该工作负荷,请选择“工具”>“获取工具和功能”添加该工作负荷。

  • 必须有一个 Azure 帐户才能将 WebJobs SDK 项目发布到 Azure。

创建一个项目

  1. 在 Visual Studio 中,选择“新建项目”。

  2. 选择“控制台应用(.NET Core)”。

  3. 将项目命名为 WebJobsSDKSample,然后选择“创建”。

    “新建项目”对话框

WebJobs NuGet 包

  1. 安装 Microsoft.Azure.WebJobs.Extensions NuGet 包的最新稳定版本 3.x,其中包括 Microsoft.Azure.WebJobs。

    下面是包管理器控制台命令:

    Install-Package Microsoft.Azure.WebJobs.Extensions -version <3_X_VERSION>
    

    在此命令中,将 <3_X_VERSION> 替换为包的受支持版本。

创建主机

主机是函数的运行时容器,它侦听触发器并调用函数。 以下步骤创建一个实现 IHost 的主机,它是 ASP.NET Core 中的通用主机。

  1. 在 Program.cs 中,添加以下 using 语句:

    using System.Threading.Tasks;
    using Microsoft.Extensions.Hosting;
    
  2. 将 Main 方法替换为以下代码:

    static async Task Main()
    {
        var builder = new HostBuilder();
        builder.ConfigureWebJobs(b =>
                {
                    b.AddAzureStorageCoreServices();
                });
        var host = builder.Build();
        using (host)
        {
            await host.RunAsync();
        }
    }
    

在 ASP.NET Core 中,通过调用 HostBuilder 实例上的方法来设置主机配置。 有关详细信息,请参阅 .NET 通用主机。 ConfigureWebJobs 扩展方法初始化 WebJobs 主机。 在 ConfigureWebJobs 中,初始化特定的 WebJobs 扩展并设置这些扩展的属性。

启用控制台日志记录

本部分介绍如何设置使用 ASP.NET Core 记录框架的控制台日志记录。

  1. 安装 Microsoft.Extensions.Logging.Console NuGet 包的最新稳定版本,其中包括 Microsoft.Extensions.Logging。

    下面是“包管理器控制台”命令:

    Install-Package Microsoft.Extensions.Logging.Console -version <3_X_VERSION>
    

    在此命令中,将 <3_X_VERSION> 替换为包的受支持的 3.x 版本。

  2. 在 Program.cs 中,添加 using 语句:

    using Microsoft.Extensions.Logging;
    
  3. 在 HostBuilder 上调用 ConfigureLogging 方法。 AddConsole 方法将控制台日志记录添加到配置中。

    builder.ConfigureLogging((context, b) =>
    {
        b.AddConsole();
    });
    

    现在,Main 方法如下所示:

    static async Task Main()
    {
        var builder = new HostBuilder();
        builder.ConfigureWebJobs(b =>
                {
                    b.AddAzureStorageCoreServices();
                });
        builder.ConfigureLogging((context, b) =>
                {
                    b.AddConsole();
                });
        var host = builder.Build();
        using (host)
        {
            await host.RunAsync();
        }
    }
    

    此项更新执行以下操作:

    • 禁用仪表板日志记录。 仪表板是一个旧式监视工具,不建议对高吞吐量生产方案使用仪表板日志记录。
    • 使用默认筛选添加控制台提供程序。

现在即可添加由到达 Azure 存储队列的消息触发的函数。

安装存储绑定扩展

从版本 3.x 开始,必须显式安装 WebJobs SDK 所需的存储绑定扩展。 在以前版本中,存储绑定已包含在 SDK 中。

  1. 安装 Microsoft.Azure.WebJobs.Extensions.Storage NuGet 包的最新稳定版本,即 3.x 版。

    下面是包管理器控制台命令:

    Install-Package Microsoft.Azure.WebJobs.Extensions.Storage -Version <3_X_VERSION>
    

    在此命令中,将 <3_X_VERSION> 替换为包的受支持版本。

  2. 在 ConfigureWebJobs 扩展方法中,调用 HostBuilder 实例上的 AddAzureStorage 方法来初始化存储扩展。 此时,ConfigureWebJobs 方法如下例所示:

    builder.ConfigureWebJobs(b =>
                    {
                        b.AddAzureStorageCoreServices();
                        b.AddAzureStorage();
                    });
    

创建函数

  1. 右键单击项目,选择“添加” > “新建项...”,选择“类”,将新的 C# 类文件命名为 Functions.cs,然后选择“添加”。

  2. 在 Functions.cs 中,使用以下代码替换生成的模板:

    using Microsoft.Azure.WebJobs;
    using Microsoft.Extensions.Logging;
    
    namespace WebJobsSDKSample
    {
        public class Functions
        {
            public static void ProcessQueueMessage([QueueTrigger("queue")] string message, ILogger logger)
            {
                logger.LogInformation(message);
            }
        }
    }
    

    QueueTrigger 特性告知运行时,在名为 queue 的 Azure 存储队列中写入新消息时,应调用此函数。 队列消息的内容将提供给 message 参数中的方法代码。 在方法的正文中处理触发器数据。 在此示例中,代码只是记录消息。

    message 参数不一定要是字符串。 也可以绑定到 JSON 对象、字节数组或 CloudQueueMessage 对象。 参阅队列触发器用法。 每个绑定类型(例如队列、Blob 或表)具有一组可以绑定到的不同参数类型。

创建存储帐户

本地运行的 Azure 存储模拟器不具有 Web 作业 SDK 所需的所有功能。 因此,在本部分,我们应在 Azure 中创建一个存储帐户,并将项目配置为使用该帐户。 如果已有一个存储帐户,请跳到步骤 6。

  1. 在 Visual Studio 中打开“服务器资源管理器”并登录 Azure。 右键单击“Azure”节点,选择“连接到 Microsoft Azure 订阅”。

    登录 Azure

  2. 在“服务器资源管理器”中的“Azure”节点下,右键单击“存储”并选择“创建存储帐户”。

    “创建存储帐户”菜单

  3. 在“创建存储帐户”对话框中,输入存储帐户的唯一名称。

  4. 选择在其中创建了应用服务应用的同一区域或者靠近的区域。

  5. 选择“创建” 。

    创建存储帐户

  6. 在“服务器资源管理器”中的“存储”节点下,选择新存储帐户。 在“属性”窗口中,选择“连接字符串”值字段右侧的省略号 ( ... )。

    “连接字符串”右侧的省略号

  7. 复制连接字符串并将此值保存在某处,以方便再次复制。

    复制连接字符串

将存储配置为在本地运行

WebJobs SDK 在 Azure 的“应用程序设置”中查找存储连接字符串。 在本地运行时,它会在本地配置文件或环境变量中查找此值。

  1. 右键单击项目,选择“添加” > “新建项...”,选择“JavaScript JSON 配置文件”,将新文件命名为 appsettings.json,然后选择“添加”。

  2. 在新文件中添加 AzureWebJobsStorage 字段,如以下示例所示:

    {
        "AzureWebJobsStorage": "{storage connection string}"
    }
    
  3. 将 {storage connection string} 替换为先前复制的连接字符串。

  4. 在解决方案资源管理器中选择“appsettings.json”文件,在“属性”窗口中,将“复制到输出目录”设置为“如果较新则复制”。

稍后,你将在 Azure 应用服务中的应用中添加相同的连接字符串应用设置。

本地测试

在本部分,我们将生成并在本地运行项目,然后通过创建队列消息来触发函数。

  1. 按 Ctrl+F5 运行项目。

    控制台显示运行时已找到函数,并等待队列消息触发该函数。 v3.x 主机生成以下输出:

     info: Microsoft.Azure.WebJobs.Hosting.JobHostService[0]
           Starting JobHost
     info: Host.Startup[0]
           Found the following functions:
           WebJobsSDKSample.Functions.ProcessQueueMessage
    
     info: Host.Startup[0]
           Job host started
     Application started. Press Ctrl+C to shut down.
     Hosting environment: Development
     Content root path: C:\WebJobsSDKSample\WebJobsSDKSample\bin\Debug\netcoreapp2.1\
    
  2. 关闭控制台窗口。

  3. 在 Visual Studio 的“服务器资源管理器”中,展开新存储帐户所在的节点,然后右键单击“队列”。

  4. 选择“创建队列”。

  5. 输入 queue 作为队列名称,然后选择“确定”。

    屏幕截图,显示创建队列的位置,并将其命名为 "queue"。

  6. 右键单击新队列所在的节点,然后选择“查看队列”。

  7. 选择“添加消息”图标。

    突出显示 "添加消息" 图标的屏幕截图。

  8. 在“添加消息”对话框中,输入 Hello World! 作为消息正文,然后选择“确定”。 现在,队列中会出现一条消息。

    创建队列

  9. 再次运行该项目。

    由于在 ProcessQueueMessage 函数中使用了 QueueTrigger 特性,因此 WeJobs SDK 运行时会在启动时侦听队列消息。 它会在名为 queue 的队列中查找新队列消息,并调用函数。

    由于队列轮询指数退让,运行时最长可能需要花费 2 分钟才能找到消息并调用函数。 以开发模式运行可以缩减此等待时间。

    控制台输出如下所示:

     info: Function.ProcessQueueMessage[0]
           Executing 'Functions.ProcessQueueMessage' (Reason='New queue message detected on 'queue'.', Id=2c319369-d381-43f3-aedf-ff538a4209b8)
     info: Function.ProcessQueueMessage[0]
           Trigger Details: MessageId: b00a86dc-298d-4cd2-811f-98ec39545539, DequeueCount: 1, InsertionTime: 1/18/2019 3:28:51 AM +00:00
     info: Function.ProcessQueueMessage.User[0]
           Hello World!
     info: Function.ProcessQueueMessage[0]
           Executed 'Functions.ProcessQueueMessage' (Succeeded, Id=2c319369-d381-43f3-aedf-ff538a4209b8)
    
  10. 关闭控制台窗口。

  11. 返回“队列”窗口并刷新。 消息已消失,因为已由本地运行的函数处理了。

添加 Application Insights 日志记录

在 Azure 中运行项目时,无法通过查看控制台输出来监视函数执行。 我们建议的监视解决方案是 Application Insights。 有关详细信息,请参阅监视 Azure Functions。

在本部分,我们将执行以下任务来设置 Application Insights 日志记录,然后部署到 Azure:

  • 请确保已准备好要使用的应用服务应用和 Application Insights 实例。
  • 将应用服务应用配置为使用前面创建的 Application Insights 实例和存储帐户。
  • 设置项目,以便将日志记录到 Application Insights。

创建应用服务应用和 Application Insights 实例

  1. 如果没有可用的应用服务应用,请创建一个。 创建应用时,还可以创建已连接的 Application Insights 资源。 执行此操作时,系统会在应用中为你设置 APPINSIGHTS_INSTRUMENTATIONKEY。

  2. 如果没有可用的 Application Insights 资源,请创建一个。 将“应用程序类型”设置为“常规”,并跳过“复制检测密钥”后面的部分。

  3. 如果已有可用的 Application Insights 资源,请复制检测密钥。

配置应用设置

  1. 在 Visual Studio 的“服务器资源管理器”中,展开“Azure”下面的“应用服务”节点。

  2. 展开应用服务应用所在的资源组,然后右键单击应用服务应用。

  3. 选择“查看设置”。

  4. 在“连接字符串”框中添加以下条目。

    名称 连接字符串 数据库类型
    AzureWebJobsStorage {前面复制的存储连接字符串} 自定义
  5. 如果“应用程序设置”框中没有 Application Insights 检测密钥,请添加前面复制的检测密钥。 (根据应用服务应用的创建方式,该框中可能已包含检测密钥。)

    名称 值
    APPINSIGHTS_INSTRUMENTATIONKEY {instrumentation key}
  6. 将 {instrumentation key} 替换为所用 Application Insights 资源中的检测密钥。

  7. 选择“保存”。

  8. 向项目添加 Application Insights 连接,以便在本地运行。 在“appsettings.json”文件中,添加 APPINSIGHTS_INSTRUMENTATIONKEY 字段,如下例所示:

    {
        "AzureWebJobsStorage": "{storage connection string}",
        "APPINSIGHTS_INSTRUMENTATIONKEY": "{instrumentation key}"
    }
    

    将 {instrumentation key} 替换为所用 Application Insights 资源中的检测密钥。

  9. 保存所做更改。

添加 Application Insights 日志记录提供程序

若要利用 Application Insights 日志记录,请更新日志记录代码以执行以下操作:

  • 使用默认筛选功能添加 Application Insights 日志记录提供程序。 在本地运行时,所有信息和更高级别日志都会同时写入控制台和 Application Insights。
  • 将 LoggerFactory 对象放在 using 块中,以确保在主机退出时刷新日志输出。
  1. 安装 Microsoft.Azure.WebJobs.Logging.ApplicationInsights NuGet 包 的最新稳定 3.x 版本。

    下面是包管理器控制台命令:

    Install-Package Microsoft.Azure.WebJobs.Logging.ApplicationInsights -Version <3_X_VERSION>
    

    在此命令中,将 <3_X_VERSION> 替换为包的受支持版本。

  2. 打开“Program.cs”并使用以下代码替换 Main 方法中的代码:

    static async Task Main()
    {
        var builder = new HostBuilder();
        builder.UseEnvironment(EnvironmentName.Development);
        builder.ConfigureWebJobs(b =>
                {
                    b.AddAzureStorageCoreServices();
                    b.AddAzureStorage();
                });
        builder.ConfigureLogging((context, b) =>
                {
                    b.AddConsole();
    
                    // If the key exists in settings, use it to enable Application Insights.
                    string instrumentationKey = context.Configuration["APPINSIGHTS_INSTRUMENTATIONKEY"];
                    if (!string.IsNullOrEmpty(instrumentationKey))
                    {
                        b.AddApplicationInsightsWebJobs(o => o.InstrumentationKey = instrumentationKey);
                    }
                });
        var host = builder.Build();
        using (host)
        {
            await host.RunAsync();
        }
    }
    

    这会使用之前添加到应用设置中的密钥将 Application Insights 提供程序添加到日志记录中。

测试 Application Insights 日志记录

在本部分,我们将再次在本地运行,以验证日志记录数据现在是否转到 Application Insights 和控制台。

  1. 使用 Visual Studio 中的服务器资源管理器创建队列消息,就像你之前所做的那样,但这次输入“Hello App Insights!” 作为消息文本。

  2. 运行该项目。

    WebJobs SDK 将处理队列消息,控制台窗口中会显示日志。

  3. 关闭控制台窗口。

  4. 转到 Azure 门户以查看 Application Insights 资源。 搜索并选择“Application Insights”。

  5. 选择 Application Insights 实例。

  6. 选择“搜索”。

    选择“搜索”

  7. 如果未看到“Hello App Insights!” 消息,请定期选择“刷新”几分钟。 (日志不会立即显示,因为 Application Insights 客户端需要一段时间来刷新它处理的日志。)

    Application Insights 中的日志

  8. 关闭控制台窗口。

部署到 Azure

在部署期间,可以创建一个要在其中运行函数的应用服务实例。 将 .NET Core 控制台应用发布到 Azure 中的应用服务时,该应用会自动以 WebJob 的形式运行。 若要详细了解发布过程,请参阅使用 Visual Studio 开发和部署 WebJob。

  1. 在“解决方案资源管理器” 中,右键单击该项目并选择“发布” 。

  2. 在 " 发布 " 对话框中,选择 " Azure " 作为 目标,然后选择 " 下一步"。

  3. 选择特定目标 Azure WebJobs ,然后选择 "下一步"。

  4. 选择 " 创建新的 Azure WebJob"。

    选取发布目标

  5. 在 **应用服务 (Windows) ** "对话框中,使用下表中的托管设置。

    设置 建议的值 说明
    名称 全局唯一名称 用于唯一标识新 Function App 的名称。
    订阅 选择订阅 要使用的 Azure 订阅。
    资源组 myResourceGroup 要在其中创建函数应用的资源组的名称。 选择“新建” 创建新的资源组。
    托管计划 应用服务计划 应用服务计划指定托管应用的 Web 服务器场的位置、大小和功能。 可以在托管多个应用时节省资金,方法是将多个 Web 应用配置为共用单个应用服务计划。 应用服务计划定义区域、实例大小、规模计数和 SKU(免费、共享、基本、标准或高级)。 然后,选择“新建”**** 以创建一个新的应用服务计划。

    “创建应用服务”对话框

  6. 选择 " 创建 ",使用这些设置在 Azure 中创建 WebJob 和相关资源,并部署项目代码。

触发 Azure 中的函数

  1. 确保不是在本地运行(如果控制台窗口仍旧打开,请将其关闭)。 否则,本地实例可能是处理所创建的任何队列消息的第一个实例。

  2. 在 Visual Studio 的“队列”页中,像以前一样向队列添加消息。

  3. 刷新“队列”页后新消息消失,因为它已由 Azure 中运行的函数处理。

    TIP 若要在 Azure 中进行测试,请使用开发模式来确保立即调用队列触发函数,并避免队列轮询指数退让导致的延迟。

在 Application Insights 中查看日志

  1. 打开 Azure 门户并转到 Application Insights 资源。

  2. 选择“搜索”。

  3. 如果未看到“Hello Azure!” 消息,请定期选择“刷新”几分钟。

    查看 WebJob 中运行的函数发出的日志,包括在上一部分中输入的 Hello Azure! 文本。

添加输入绑定

输入绑定可以简化读取数据的代码。 在本示例中,队列消息是 Blob 名称,我们将使用该 Blob 名称来查找和读取 Azure 存储中的 Blob。

  1. 在 Functions.cs 中,将 ProcessQueueMessage 方法替换为以下代码:

    public static void ProcessQueueMessage(
        [QueueTrigger("queue")] string message,
        [Blob("container/{queueTrigger}", FileAccess.Read)] Stream myBlob,
        ILogger logger)
    {
        logger.LogInformation($"Blob name:{message} \n Size: {myBlob.Length} bytes");
    }
    

    在此代码中,queueTrigger 是绑定表达式,意味着它将在运行时解析为不同的值。 在运行时,它具有队列消息的内容。

  2. 添加 using:

    using System.IO;
    
  3. 在存储帐户中创建 Blob 容器。

    a. 在 Visual Studio 的“服务器资源管理器”中,展开你的存储帐户所在的节点,右键单击“Blob”,并选择“创建 Blob 容器”。

    b. 在“创建 Blob 容器”对话框中,输入 container 作为容器名称,然后单击“确定”。

  4. 将 Program.cs 文件上传到 Blob 容器。 (此处使用的文件用作示例;可以上传任何文本文件,并使用该文件的名称创建队列消息。)

    a. 在“服务器资源管理器”中,双击创建的容器所在的节点。

    b. 在“容器”窗口中,选择“上传”按钮 。

    Blob 上传按钮

    c. 找到并选择“Program.cs”,然后选择“确定”。

  5. 在前面创建的队列中创建队列消息,并使用 Program.cs 作为消息的文本。

    队列消息 Program.cs

  6. 在本地运行项目

    该队列消息会触发函数,而该函数又会读取 Blob 并记录其长度。 控制台输出如下所示:

    Found the following functions:
    ConsoleApp1.Functions.ProcessQueueMessage
    Job host started
    Executing 'Functions.ProcessQueueMessage' (Reason='New queue message detected on 'queue'.', Id=5a2ac479-de13-4f41-aae9-1361f291ff88)
    Blob name:Program.cs
    Size: 532 bytes
    Executed 'Functions.ProcessQueueMessage' (Succeeded, Id=5a2ac479-de13-4f41-aae9-1361f291ff88)
    

添加输出绑定

输出绑定可以简化写入数据的代码。 本示例在前一个示例的基础上做了修改,它会写入 Blob 的副本,而不是记录其大小。 Blob 存储绑定包含在我们之前安装的 Azure 存储扩展包中。

  1. 将 ProcessQueueMessage方法替换为以下代码:

    public static void ProcessQueueMessage(
        [QueueTrigger("queue")] string message,
        [Blob("container/{queueTrigger}", FileAccess.Read)] Stream myBlob,
        [Blob("container/copy-{queueTrigger}", FileAccess.Write)] Stream outputBlob,
        ILogger logger)
    {
        logger.LogInformation($"Blob name:{message} \n Size: {myBlob.Length} bytes");
        myBlob.CopyTo(outputBlob);
    }
    
  2. 创建另一个队列消息,并使用 Program.cs 作为消息的文本。

  3. 在本地运行项目

    该队列消息会触发函数,而该函数又会读取 Blob、记录其长度并创建新 Blob。 控制台输出相同,但在转到 Blob 容器窗口并选择“刷新”时,会看到名为 copy-Program.cs 的新 Blob。

将更新重新发布到 Azure

  1. 在“解决方案资源管理器” 中,右键单击该项目并选择“发布”。

  2. 在“发布”对话框中,确保当前配置文件已选中,然后选择“发布”。 “输出”窗口中会详细显示发布结果。

  3. 通过再次将某个文件上传到 Blob 容器,并将一条消息添加到与所上传文件同名的队列,来验证 Azure 中的函数。 将会看到,该消息已从队列中删除,并且 Blob 容器中创建了该文件的副本。

后续步骤

本文介绍了如何创建、运行和部署 WebJobs SDK 3.x 项目。

详细了解 WebJobs SDK

历史资料。此文对应 2022-08-12 的中文文档快照,适用产品版本和命令行为以原文为准。

来源与署名:Microsoft 和文档贡献者(原始作者元数据 ggailey777)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体、发布器占位标签和导航标记。

资料来源与适用范围

资料来源
Microsoft / Azure 中文运维文档历史快照
适用范围
历史中文快照 2022-08-12;详见原文产品版本;文档日期 02/18/2019
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0(文档)/ MIT(示例代码)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。