WebJobs Instance Execution Rules and Single-Instance Configuration Guide

In Azure App Service, the number of running instances of a WebJob is determined by the WebJob type and configuration, not by the number of application instances. Understanding these rules helps avoid duplicate execution and ensures tasks run on appropriate instances. Based on official documentation and experiments, this article summarizes the default behaviors of different WebJob types and provides concrete methods to restrict a continuous WebJob to a single instance.

1. WebJob Types and Default Behavior

App Service supports three main WebJob types:

Continuous WebJob (Continuous) By default, runs continuously on all instances of the application, suitable for long‑running tasks such as polling queues or background monitoring. (Source: Microsoft Docs "WebJobs Overview")
Triggered WebJob (Triggered) Includes manual and scheduled triggers. Each trigger causes the platform to select one instance to run the job; it does not run on all instances simultaneously. (Source: Microsoft Docs "WebJobs Overview")
Scheduled WebJob (Scheduled) A type of triggered WebJob, triggered according to a NCRONTAB expression, and follows the same default single‑instance execution behavior.

2. Behavior in Multi‑Instance Environments

Assume the application scales to three instances. The behavior of different WebJob types is as follows:

WebJob Type	Default Behavior	Steady State in a 3‑Instance Environment
Continuous (multi‑instance)	Starts a task on each instance	Three task processes run continuously
Continuous (single‑instance)	After setting `is_singleton: true`, runs on only one instance	One task process runs continuously
Manual trigger	Each trigger selects one instance to execute	Clicking Run once starts one execution
Scheduled trigger	Each trigger point is executed by one instance	Each trigger starts one execution, not three

Experimental record: A test on cnblogs used the same PowerShell script, deploying four WebJobs in a 3‑instance environment, verifying the above behavior (Source: cnblogs "App Service WebJobs Multi‑instance Experiment: Who is Running, When is it Running?"").

Note: For triggered WebJobs, "one instance" does not mean a fixed machine. The executing instance may change on subsequent triggers, after instance replacement, or when a single‑instance continuous task takes over. The platform does not guarantee that manual triggers will round‑robin across A, B, C; clicking several times and always landing on A does not violate the rule.

3. Restricting a Continuous WebJob to a Single Instance

If a continuous task cannot run on multiple instances simultaneously (e.g., writing to a shared resource), you can limit it to a single instance using either of the following methods:

3.1 Using the `settings.job` File

Add or update a settings.job file in the root of the WebJob folder with the following content:

{
  \"is_singleton\": true
}

For a scheduled WebJob, you can also specify a schedule expression:

{
  \"schedule\": \"0 */5 * * * *\",
  \"is_singleton\": true
}

Source: Microsoft Docs state that "you can restrict a WebJob to a single instance" and provide examples of the settings.job file.

3.2 Using the Application Setting `WEBJOBS_RUN_ONCE`

In the Azure portal, under Application Settings, add:

Name: WEBJOBS_RUN_ONCE
Value: 1

This setting causes a continuous WebJob to run on only one instance.

Source: Microsoft Docs "WebJobs Overview" mentions that the WEBJOBS_RUN_ONCE setting can be used to limit single‑instance execution.

4. Experimental Verification Steps

The following steps can be used to verify multi‑instance behavior yourself:

Prepare a PowerShell script that outputs the current instance ID, UTC time, and run batch. An example script is provided in the cnblogs experiment article.
Package the script into four ZIP files: continuous-multi.zip, continuous-single.zip, manual.zip, scheduled.zip.
In the Azure portal, create four WebJobs for the same App Service, upload the corresponding ZIP files, and set the types to continuous (multi‑instance), continuous (single‑instance), manual trigger, and scheduled trigger.
Ensure the application scales to at least three instances.
Trigger each WebJob and view the Kudu logs, recording the instance ID for each execution.

Tip: In the experiment, the continuous single‑instance WebJob must have is_singleton: true configured in settings.job; otherwise it defaults to multi‑instance.

5. Caveats and Limitations

Free/Shared Pricing Tiers: Multi‑instance execution options are only available on Basic, Standard, and Premium pricing tiers (Source: Microsoft Docs "Run background tasks with WebJobs").
Always On: For scheduled or continuous WebJobs, it is recommended to enable "Always On" to prevent scheduling timeouts when the application is idle.
Overlapping Triggered WebJobs: By default, if a previous run is still in progress, a new trigger may start in parallel on the same instance. To enforce serial execution, set is_singleton: true in settings.job (Source: Microsoft Docs Q&A).

6. Next Steps

Check the current App Service pricing tier to ensure it supports multi‑instance configuration.
Choose the appropriate WebJob type based on the task and configure settings.job or application settings as needed.
Verify the behavior in a staging environment using the experimental method described above before deploying to production.

References

Microsoft Docs, "WebJobs Overview" (learn.microsoft.com)
Microsoft Docs, "Run background tasks with WebJobs" (learn.microsoft.com)
Microsoft Docs Q&A, "Azure Webjob: Type Triggered, works with singleton principle or not?"
cnblogs, "App Service WebJobs Multi‑instance Experiment: Who is Running, When is it Running?"

By understanding the instance selection mechanism of WebJobs, you can precisely control where background tasks run, avoid duplicate processing, and improve application reliability.