You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Understand how WebJobs are discovered, triggered, and managed by the Kudu engine in Azure App Service.
3
+
description: Learn how the Kudu engine discovers, triggers, and manages WebJobs in Azure App Service. Azure WebJobs can run background tasks in your app.
4
4
ms.topic: conceptual
5
5
ms.service: azure-app-service
6
6
author: msangapu-msft
7
7
ms.author: msangapu
8
-
ms.date: 05/01/2025
8
+
ms.date: 12/02/2025
9
9
ms.update-cycle: 180-days
10
10
ms.collection: ce-skilling-ai-copilot
11
+
#customer intent: As an app developer, I need to understand how WebJobs work in Azure App Service to discover and manage background tasks.
11
12
---
12
13
13
14
# How WebJobs run in Azure App Service
14
15
15
-
Azure WebJobs allow you to run background tasks within your App Service app, without needing separate infrastructure. The Kudu engine discovers and manages these tasks. The Kudu engine is the built-in App Service deployment and runtime management service. Kudu handles WebJob execution, file system access, diagnostics, and log collection behind the scenes.
16
+
Azure WebJobs allow you to run background tasks in your App Service app, without needing separate infrastructure. The Kudu engine discovers and manages these tasks. The Kudu engine is the built-in App Service deployment and runtime management service. Kudu handles WebJob execution, file system access, diagnostics, and log collection behind the scenes.
16
17
17
-
This article explains how WebJobs are discovered, how the runtime decides what to execute, and how you can configure behavior using the optional `settings.job` file.
18
+
This article explains how WebJobs are discovered, how the runtime decides what to run, and how you can configure behavior using the optional `settings.job` file.
18
19
19
20
## Platform-specific notes
20
21
21
-
WebJobs support various script and executable formats, depending on the App Service hosting environment. The types of files you can run—and the runtimes available—vary slightly based on whether you're using Windows code, Linux code, or custom containers. In general, built-in runtimes are available for common scripting languages. Other file types are supported when they match the language runtime of your app or container.
22
+
WebJobs support various script and executable formats, depending on the App Service hosting environment. The types of files you can runand the runtimes available vary based on whether you're using Windows code, Linux code, or custom containers. In general, built-in runtimes are available for common scripting languages. Other file types are supported when they match the language runtime of your app or container.
> WebJobs that are continuous, scheduled, or event-driven might stop running if the web app hosting them becomes idle. Web apps can time out after 20 minutes of inactivity, and only direct requests to the app reset this idle timer. Actions like viewing the portal or accessing the Kudu tools don't keep the app active.
27
-
> To ensure WebJobs run reliably, enable the Always on setting in the Configuration pane of your App Service.
26
+
> [!IMPORTANT]
27
+
> WebJobs that are continuous, scheduled, or event-driven might stop running if the web app that hosts them becomes idle. Web apps can time out after 20 minutes of inactivity, and only direct requests to the app reset this idle timer. Actions like viewing the portal or accessing the Kudu tools don't keep the app active.
28
+
>
29
+
> To ensure WebJobs run reliably, enable the **Always on** setting in the **Configuration** pane of your App Service.
30
+
>
28
31
> This setting is available only in the Basic, Standard, and Premium pricing tiers.
29
32
30
33
## Job discovery and folder structure
@@ -36,43 +39,42 @@ WebJobs are stored in the `site/wwwroot/App_Data/jobs/` folder of your App Servi
36
39
37
40
Each job has its own subfolder under the corresponding type, named after the WebJob. For example:
38
41
39
-
```
40
-
App_Data/jobs/triggered/myjob/
41
-
App_Data/jobs/continuous/myjob/
42
-
```
42
+
`App_Data/jobs/triggered/myjob/`
43
+
`App_Data/jobs/continuous/myjob/`
43
44
44
-
Inside the job folder, the Kudu engine looks for a file to execute. This file can be a script or executable.
45
+
Inside the job folder, the Kudu engine looks for a file to run. This file can be a script or executable.
45
46
46
47
## Entry point detection
47
48
48
-
The WebJobs runtime uses a file named `run.*` (such as `run.py`, `run.sh`, or `run.js`) as the explicit entry point for a job. This file tells the platform which script or binary to execute first, ensuring consistent and predictable behavior across environments.
49
+
The WebJobs runtime uses a file named `run.*`, such as `run.py`, `run.sh`, or `run.js`, as the explicit entry point for a job. This file tells the platform which script or binary to execute first, which ensures consistent and predictable behavior across environments.
49
50
50
51
The filename must be exactly `run.*` to be autodetected. Files like `start.sh` or `job.py` are ignored unless manually triggered. If no `run.*` file is found, the platform attempts to detect a fallback entry point by selecting the first supported file based on the language platform of the WebJob. For example:
51
52
52
53
- A Python WebJob with multiple `.py` files (for example, `file1.py`, `file2.py`) runs the first `.py` file it finds in the archive.
53
54
- A Node.js WebJob looks for the first `.js` file.
54
55
- A Bash-based WebJob looks for the first `.sh` script.
55
56
56
-
This fallback behavior can lead to unpredictable execution when multiple script files are present—especially in multi-file projects. We recommended that you include a `run.*` file to define the entry point explicitly.
57
+
If multiple script files are present, especially in multi-file projects, this fallback behavior can lead to unpredictable execution. We recommended that you include a `run.*` file to define the entry point explicitly.
57
58
58
59
On Linux-based WebJobs, `.sh` scripts must include a shebang (`#!`) and must be marked as executable.
59
60
60
61
## WebJob configuration with settings.job
61
62
62
-
You can customize WebJob behavior using an optional `settings.job` file (JSON format) placed in the job's root folder. This file supports several properties:
63
+
You can customize WebJob behavior using an optional `settings.job` file (JSON format) in the job's root folder. This file supports several properties:
63
64
64
-
| Property | Description |
65
-
|----------|-------------|
66
-
|`schedule`|(string) A CRON expression used to schedule a triggered job. Example: `"0 */15 * * * *"`. Only applicable to triggered jobs. |
67
-
|`is_singleton`|(bool) Ensures only one instance of the job runs across all scaled-out instances. Default: `true` for continuous jobs, `false` for triggered/on-demand. |
68
-
|`stopping_wait_time`|(number, seconds) Grace period (default 5 seconds) given to the script before it's killed when the WebJob is stopped (for example, during site swaps or restarts). |
69
-
|`shutdownGraceTimeLimit`|(number, seconds) Max time (default 0s, meaning no limit) given for the entire WebJob process shutdown, including the `stopping_wait_time`, before it's forcefully terminated. |
70
-
|`run_mode`|(string) Values: `continuous`, `scheduled`, `on_demand`. Overrides job type detection based on the folder. |
65
+
| Property |Format |Description |
66
+
|----------|------|-------|
67
+
|`schedule`| string| A CRON expression used to schedule a triggered job. Example: `"0 */15 * * * *"`. Only applicable to triggered jobs. |
68
+
|`is_singleton`| bool| Ensures only one instance of the job runs across all scaled-out instances. Default: `true` for continuous jobs, `false` for triggered/on-demand. |
69
+
|`stopping_wait_time`| number, seconds|Grace period (default 5 seconds) given to the script before it stops when the WebJob stops, for example, during site swaps or restarts. |
70
+
|`shutdownGraceTimeLimit`| number, seconds| Max time (default 0s, meaning no limit) given for the entire WebJob process shutdown, including the `stopping_wait_time`, before it's forcefully terminated. |
71
+
|`run_mode`| string| Values: `continuous`, `scheduled`, `on_demand`. Overrides job type detection based on the folder. |
71
72
72
73
> [!NOTE]
73
-
> `stopping_wait_time` applies specifically to the running script's grace period, while `shutdownGraceTimeLimit` defines the overall process shutdown timeout. Consult the [Kudu documentation](https://github.com/projectkudu/kudu/wiki/WebJobs) for detailed behavior.
74
+
> `stopping_wait_time` applies specifically to the running script's grace period, while `shutdownGraceTimeLimit` defines the overall process shutdown timeout. For more information, see [Kudu documentation](https://github.com/projectkudu/kudu/wiki/WebJobs).
74
75
75
76
### Example
77
+
76
78
```json
77
79
{
78
80
"schedule": "0 0 * * * *", // Run once at the top of every hour
@@ -84,24 +86,25 @@ You can customize WebJob behavior using an optional `settings.job` file (JSON fo
84
86
85
87
## Logging and diagnostics
86
88
87
-
The Kudu engine handles WebJob logs. They're available under the `App_Data/jobs/<type>/<jobname>` folder. Additionally, logs can be viewed in the Azure portal or accessed via the SCM (Kudu) endpoint:
89
+
The Kudu engine handles WebJob logs. They're available in the `App_Data/jobs/<type>/<jobname>` folder. Additionally, logs can be viewed in the Azure portal or accessed by using the SCM (Kudu) endpoint:
For more advanced monitoring and querying capabilities, consider integrating with [Application Insights](/azure/azure-monitor/app/app-insights-overview).
93
96
94
97
Triggered WebJobs include a full history of executions. Continuous WebJobs stream logs in real time.
95
98
96
99
## Troubleshooting tips
97
100
98
-
-**WebJob not starting:** Check for a missing or misnamed `run.*` file. Ensure it's in the correct job folder (`triggered` or `continuous`).
101
+
-**WebJob not starting:** Check for a missing or misnamed `run.*` file. Ensure it's in the correct job folder: `triggered` or `continuous`.
99
102
-**Permissions error (Linux):** Ensure the script has execute permissions (`chmod +x run.sh`) and includes a valid shebang (for example, `#!/bin/bash`).
100
103
-**Job not stopping gracefully:** Use `settings.job` to define `stopping_wait_time` and potentially `shutdownGraceTimeLimit`.
101
104
-**Scheduled job not running:** Verify the CRON expression in `settings.job` is correct and the App Service Plan has "Always On" enabled if needed.
102
-
-**Check Kudu logs:** Examine the detailed execution logs and deployment logs available in the Kudu console (`https://<your-app>.scm.azurewebsites.net/`) under Tools > WebJobs and potentially Log stream.
105
+
-**Check Kudu logs:** Examine the detailed execution logs and deployment logs available in the Kudu console (`https://<your-app>.scm.azurewebsites.net/`) under **Tools** > **WebJobs** and potentially Log stream.
103
106
104
-
## <aname="NextSteps"></a> Next steps
107
+
## <aname="NextSteps"></a> Related content
105
108
106
109
-[WebJobs overview](overview-webjobs.md)
107
110
-[Create a scheduled WebJob](quickstart-webjobs.md)
0 commit comments