Azure Functions 预热触发器Azure Functions warm-up trigger

本文介绍了如何在 Azure Functions 中使用预热触发器。This article explains how to work with the warmup trigger in Azure Functions. 只有在高级计划中运行的函数应用支持预热触发器。The warmup trigger is supported only for function apps running in a Premium plan. 当添加实例来缩放正在运行的函数应用时,将调用预热触发器。A warmup trigger is invoked when an instance is added to scale a running function app. 你可以在预热过程中使用预热触发器来预加载自定义依赖项,使你的函数能够准备就绪,以便立即开始处理请求。You can use a warmup trigger to pre-load custom dependencies during the pre-warming process so that your functions are ready to start processing requests immediately.

此参考信息面向 Azure Functions 开发人员。This is reference information for Azure Functions developers. Azure Functions 的新手请从以下资源入手:If you're new to Azure Functions, start with the following resources:

包 - Functions 2.x 及更高版本Packages - Functions 2.x and higher

需要 Microsoft.Azure.WebJobs.Extensions NuGet 包版本 3.0.5 或更高版本The Microsoft.Azure.WebJobs.Extensions NuGet package, version 3.0.5 or higher is required. azure-webjobs-sdk-extensions GitHub 存储库中提供了此包的源代码。Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

C# 类库C# class library

对于 C# 类库开发,自动在项目中安装该包。For C# class library development, the package is automatically installed in the project.

Functions 2.x 中的绑定扩展Binding extensions in Functions 2.x

对于 Azure Functions 2.x 版中的本地开发,该包自动注册为绑定扩展For local development in Azure Functions version 2.x, the package is automatically registered as a binding extension.

触发器Trigger

使用预热触发器,你可以定义在将新实例添加到正在运行的应用时将在新实例上运行的函数。The warmup trigger lets you define a function that will be run on a new instance when it is added to your running app. 你可以使用预热函数,在应用开始接收流量之前打开连接、加载依赖项或运行任何其他自定义逻辑。You can use a warmup function to open connections, load dependencies, or run any other custom logic before your app will begin receiving traffic.

预热触发器用于创建将由应用中的其他函数使用的共享依赖项。The warmup trigger is intended to create shared dependencies that will be used by the other functions in your app. 请在此处查看共享依赖项的示例See examples of shared dependencies here.

请注意,只有在执行横向扩展操作期间才会调用预热触发器,在重启或其他非缩放启动期间不会调用。Note that the warmup trigger is only called during scale-out operations, not during restarts or other non-scale startups. 你必须确保你的逻辑可以在不使用预热触发器的情况下加载所有必需的依赖项。You must ensure your logic can load all necessary dependencies without using the warmup trigger. 延迟加载是实现此目的的一个好模式。Lazy loading is a good pattern to achieve this.

触发器 - 示例Trigger - example

下面的示例展示了一个 C# 函数,该函数将在向应用添加新实例时在每个新实例上运行。The following example shows a C# function that will run on each new instance when it is added to your app. 不需要返回值属性。A return value attribute isn't required.

  • 函数必须命名为 warmup(不区分大小写),并且每个应用只能有一个预热函数。Your function must be named warmup (case-insensitive) and there may only be one warmup function per app.
  • 若要使用某个 .NET 类库函数作为预热函数,请确保引用 3.0.5 或更高版本的 Microsoft.Azure.WebJobs.Extensions 包。To use warmup as a .NET class library function, please make sure you have a package reference to Microsoft.Azure.WebJobs.Extensions >= 3.0.5
    • <PackageReference Include="Microsoft.Azure.WebJobs.Extensions" Version="3.0.5" />

占位符注释显示了在应用程序中声明和初始化共享依赖项的位置。Placeholder comments show where in the application to declare and initialize shared dependencies. 在此处详细了解共享依赖项Learn more about shared dependencies here.

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
 
namespace WarmupSample
{

    //Declare shared dependencies here

    public static class Warmup
    {
        [FunctionName("Warmup")]
        public static void Run([WarmupTrigger()] WarmupContext context,
            ILogger log)
        {
            //Initialize shared dependencies here
            
            log.LogInformation("Function App instance is warm 🌞🌞🌞");
        }
    }
}

触发器 - 特性Trigger - attributes

C# 类库中,WarmupTrigger 属性可用于配置函数。In C# class libraries, the WarmupTrigger attribute is available to configure the function.

此示例演示了如何使用 warmup 属性。This example demonstrates how to use the warmup attribute.

注意,函数必须命名为 Warmup,并且每个应用只能有一个预热函数。Note that your function must be called Warmup and there can only be one warmup function per app.

 [FunctionName("Warmup")]
        public static void Run(
            [WarmupTrigger()] WarmupContext context, ILogger log)
        {
            ...
        }

有关完整示例,请参阅触发器示例For a complete example, see the trigger example.

触发器 - 配置Trigger - configuration

下表解释了在 function.json 文件和 WarmupTrigger 特性中设置的绑定配置属性。The following table explains the binding configuration properties that you set in the function.json file and the WarmupTrigger attribute.

function.json 属性function.json property Attribute 属性Attribute property 说明Description
typetype 不适用n/a 必需 - 必须设置为 warmupTriggerRequired - must be set to warmupTrigger.
directiondirection 不适用n/a 必需 - 必须设置为 inRequired - must be set to in.
namename 不适用n/a 必需 - 函数代码中使用的变量名称。Required - the variable name used in function code.

触发器 - 用法Trigger - usage

调用预热触发的函数时,不会向其提供附加信息。No additional information is provided to a warmup triggered function when it is invoked.

触发器 - 限制Trigger - limits

  • 预热触发器仅适用于按高级计划运行的应用。The warmup trigger is only available to apps running on the Premium plan.
  • 只有在执行横向扩展操作期间才会调用预热触发器,在重启或其他非缩放启动期间不会调用。The warmup trigger is only called during scale-out operations, not during restarts or other non-scale startups. 你必须确保你的逻辑可以在不使用预热触发器的情况下加载所有必需的依赖项。You must ensure your logic can load all necessary dependencies without using the warmup trigger. 延迟加载是实现此目的的一个好模式。Lazy loading is a good pattern to achieve this.
  • 如果实例已在运行,则无法调用预热触发器。The warmup trigger cannot be invoked once an instance is already running.
  • 每个函数应用只能有一个预热触发器函数。There can only be one warmup trigger function per function app.

后续步骤Next steps

详细了解 Azure Functions 触发器和绑定Learn more about Azure functions triggers and bindings