Skip to content

Commit a2328ad

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #95447 from alexkarcher-msft/master
Warmup Function Documentation
2 parents 955a880 + 7c54d76 commit a2328ad

File tree

2 files changed

+263
-0
lines changed

2 files changed

+263
-0
lines changed

‎articles/azure-functions/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -362,6 +362,8 @@
362362
href: functions-bindings-timer.md
363363
- name: Twilio
364364
href: functions-bindings-twilio.md
365+
- name: Warmup
366+
href: functions-bindings-warmup.md
365367
- name: host.json 2.x reference
366368
href: functions-host-json.md
367369
- name: host.json 1.x reference

‎articles/azure-functions/functions-bindings-warmup.md

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
---
2+
title: Azure Functions warmup trigger
3+
description: Understand how to use the warmup trigger in Azure Functions.
4+
documentationcenter: na
5+
author: alexkarcher-msft
6+
manager: gwallace
7+
keywords: azure functions, functions, event processing, warmup, cold start, premium, dynamic compute, serverless architecture
8+
9+
ms.service: azure-functions
10+
ms.topic: reference
11+
ms.date: 11/08/2019
12+
ms.author: alkarche
13+
---
14+
15+
# Azure Functions warm-up trigger
16+
17+
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](functions-premium-plan.md). 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](./functions-premium-plan.md#pre-warmed-instances) so that your functions are ready to start processing requests immediately.
18+
19+
[!INCLUDE [intro](../../includes/functions-bindings-intro.md)]
20+
21+
## Packages - Functions 2.x
22+
23+
The [Microsoft.Azure.WebJobs.Extensions](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions) NuGet package, version **3.0.5 or higher** is required. Source code for the package is in the [azure-webjobs-sdk-extensions](https://github.com/Azure/azure-webjobs-sdk-extensions/blob/master/src/WebJobs.Extensions.Http/) GitHub repository.
24+
25+
[!INCLUDE [functions-package](../../includes/functions-package-auto.md)]
26+
27+
## Trigger
28+
29+
The warmup trigger lets you define a function that will be run on an 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.
30+
31+
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](./manage-connections.md#client-code-examples).
32+
33+
Note that the warmup trigger is only called during scale-up 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.
34+
35+
## Trigger - example
36+
37+
# [C#](#tab/csharp)
38+
39+
The following example shows a [C# function](functions-dotnet-class-library.md) that will run on each new instance when it is added to your app. A return value attribute isn't required.
40+
41+
42+
* Your function must be named ```warmup``` (case-insensitive) and there may only be one warmup function per app.
43+
* 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**
44+
* ```<PackageReference Include="Microsoft.Azure.WebJobs.Extensions" Version="3.0.5" />```
45+
46+
47+
Placeholder comments show where in the application to declare and initialize shared dependencies.
48+
[Learn more about shared dependencies here](./manage-connections.md#client-code-examples).
49+
50+
```cs
51+
using Microsoft.Azure.WebJobs;
52+
using Microsoft.Extensions.Logging;
53+
54+
namespace WarmupSample
55+
{
56+
57+
//Declare shared dependencies here
58+
59+
public static class Warmup
60+
{
61+
[FunctionName("Warmup")]
62+
public static void Run([WarmupTrigger()] WarmupContext context,
63+
ILogger log)
64+
{
65+
//Initialize shared dependencies here
66+
67+
log.LogInformation("Function App instance is warm 🌞🌞🌞");
68+
}
69+
}
70+
}
71+
```
72+
# [C# Script](#tab/csharp-script)
73+
74+
75+
The following example shows a warmup trigger in a *function.json* file and a [C# script function](functions-reference-csharp.md) that will run on each new instance when it is added to your app.
76+
77+
Your function must be named ```warmup``` (case-insensitive), and there may only be one warmup function per app.
78+
79+
Here's the *function.json* file:
80+
81+
```json
82+
{
83+
"bindings": [
84+
{
85+
"type": "warmupTrigger",
86+
"direction": "in",
87+
"name": "warmupContext"
88+
}
89+
]
90+
}
91+
```
92+
93+
The [configuration](#trigger---configuration) section explains these properties.
94+
95+
Here's C# script code that binds to `HttpRequest`:
96+
97+
```cs
98+
public static void Run(ILogger log)
99+
{
100+
log.LogInformation("Function App instance is warm 🌞🌞🌞");
101+
}
102+
```
103+
104+
# [JavaScript](#tab/javascript)
105+
106+
The following example shows a warmup trigger in a *function.json* file and a [JavaScript function](functions-reference-node.md) that will run on each new instance when it is added to your app.
107+
108+
Your function must be named ```warmup``` (case-insensitive) and there may only be one warmup function per app.
109+
110+
Here's the *function.json* file:
111+
112+
```json
113+
{
114+
"bindings": [
115+
{
116+
"type": "warmupTrigger",
117+
"direction": "in",
118+
"name": "warmupContext"
119+
}
120+
]
121+
}
122+
```
123+
124+
The [configuration](#trigger---configuration) section explains these properties.
125+
126+
Here's the JavaScript code:
127+
128+
```javascript
129+
module.exports = async function (context, warmupContext) {
130+
context.log('Function App instance is warm 🌞🌞🌞');
131+
context.done();
132+
};
133+
```
134+
135+
# [Python](#tab/python)
136+
137+
The following example shows a warmup trigger in a *function.json* file and a [Python function](functions-reference-python.md) that will run on each new instance when it is added to your app.
138+
139+
Your function must be named ```warmup``` (case-insensitive) and there may only be one warmup function per app.
140+
141+
Here's the *function.json* file:
142+
143+
```json
144+
{
145+
"bindings": [
146+
{
147+
"type": "warmupTrigger",
148+
"direction": "in",
149+
"name": "warmupContext"
150+
}
151+
]
152+
}
153+
```
154+
155+
The [configuration](#trigger---configuration) section explains these properties.
156+
157+
Here's the Python code:
158+
159+
```python
160+
import logging
161+
import azure.functions as func
162+
163+
164+
def main(warmupContext: func.Context) -> None:
165+
logging.info('Function App instance is warm 🌞🌞🌞')
166+
```
167+
168+
# [Java](#tab/java)
169+
170+
The following example shows a warmup trigger in a *function.json* file and a [Java functions](functions-reference-java.md) that will run on each new instance when it is added to your app.
171+
172+
Your function must be named ```warmup``` (case-insensitive) and there may only be one warmup function per app.
173+
174+
Here's the *function.json* file:
175+
176+
```json
177+
{
178+
"bindings": [
179+
{
180+
"type": "warmupTrigger",
181+
"direction": "in",
182+
"name": "warmupContext"
183+
}
184+
]
185+
}
186+
```
187+
188+
Here's the Java code:
189+
190+
```java
191+
@FunctionName("Warmup")
192+
public void run( ExecutionContext context) {
193+
context.getLogger().info("Function App instance is warm 🌞🌞🌞");
194+
}
195+
```
196+
197+
---
198+
199+
## Trigger - attributes
200+
201+
In [C# class libraries](functions-dotnet-class-library.md), the `WarmupTrigger` attribute is available to configure the function.
202+
203+
# [C#](#tab/csharp)
204+
205+
This example demonstrates how to use the [warmup](https://github.com/Azure/azure-webjobs-sdk-extensions/blob/dev/src/WebJobs.Extensions/Extensions/Warmup/Trigger/WarmupTriggerAttribute.cs) attribute.
206+
207+
Note that your function must be called ```Warmup``` and there can only be one warmup function per app.
208+
209+
```csharp
210+
[FunctionName("Warmup")]
211+
public static void Run(
212+
[WarmupTrigger()] WarmupContext context, ILogger log)
213+
{
214+
...
215+
}
216+
```
217+
218+
For a complete example, see the [trigger example](#trigger---example).
219+
220+
# [C# Script](#tab/csharp-script)
221+
222+
Attributes are not supported by C# Script.
223+
224+
# [JavaScript](#tab/javascript)
225+
226+
Attributes are not supported by JavaScript.
227+
228+
# [Python](#tab/python)
229+
230+
Attributes are not supported by Python.
231+
232+
# [Java](#tab/java)
233+
234+
The warmup trigger is not supported in Java as an attribute.
235+
236+
---
237+
238+
## Trigger - configuration
239+
240+
The following table explains the binding configuration properties that you set in the *function.json* file and the `WarmupTrigger` attribute.
241+
242+
|function.json property | Attribute property |Description|
243+
|---------|---------|----------------------|
244+
| **type** | n/a| Required - must be set to `warmupTrigger`. |
245+
| **direction** | n/a| Required - must be set to `in`. |
246+
| **name** | n/a| Required - the variable name used in function code.|
247+
248+
## Trigger - usage
249+
250+
No additional information is provided to a warmup triggered function when it is invoked.
251+
252+
## Trigger - limits
253+
254+
* The warmup trigger is only available to apps running on the [Premium plan](./functions-premium-plan.md).
255+
* The warmup trigger is only called during scale up 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.
256+
* The warmup trigger cannot be invoked once an instance is already running.
257+
* There can only be one warmup trigger function per function app.
258+
259+
## Next steps
260+
261+
[Learn more about Azure functions triggers and bindings](functions-triggers-bindings.md)

0 commit comments

Comments
 (0)