Web jobs - davidni/kudu GitHub Wiki

Ability to run a script (called job) in 2 different ways:

  1. External trigger - run the job every time an API is called.
  2. Continuous - make sure the job is always running (job should have a while loop but when it goes down we bring it back up).

Jobs are deployed by copying them to the right place in the file-system (or using a designated API which will do the same).

To deploy a triggered job copy your binaries to: site/wwwroot/app_data/jobs/triggered/{job name}

To deploy a continuous job copy your binaries to: site/wwwroot/app_data/jobs/continuous/{job name}

Note: see the Deployment section below for alternative ways of deploying WebJobs.

The following file types are accepted as runnable scripts that can be used as a job:

  • .cmd, .bat, .exe (using windows cmd)
  • .ps1 (using powershell)
  • .sh (using bash)
  • .php (using php)
  • .py (using python)
  • .js (using node)

We use the following logic to decide which file is the script to run within the job's directory:

  • Per file type we look first for a file named: run.{file type extension} (for example run.cmd or run.exe.
  • If it doesn't exists for all file types, we'll then look for the first file with a supported file type extension.
  • The order of file types extension used is: .cmd, .bat, .exe, .ps1, .sh, .php, .py, .js.
  • The recommended script file to have in your job directory is: run.cmd.
  • Note: We'll only look for a script under the root directory of that job (not under sub directories of it).

Configuration Settings

  • WEBJOBS_RESTART_TIME - Timeout in seconds between when a continuous job's process goes down (for any reason) and the time we re-launch it again (Only for continuous jobs).
  • WEBJOBS_IDLE_TIMEOUT - Time in seconds after which we'll abort a running triggered job's process if it's in idle, has no cpu time or output (Only for triggered jobs).
  • WEBJOBS_HISTORY_SIZE - Maximum number of runs kept in the history directory for a triggered job.
  • WEBJOBS_STOPPED - Set this setting to 1 to disable running any job (will also stop all currently running jobs).

Environment Settings

When a job is invoked, several settings are added to it's environment that the job process can use:

  • WEBJOBS_PATH - The root path of currently running job (will be under some temporary directory).
  • WEBJOBS_NAME - The current job name.
  • WEBJOBS_TYPE - The current job type (triggered/continuous).
  • WEBJOBS_DATA_PATH - The current job meta data path, this includes the job's logs/history and any artifact of the job can go there.
  • WEBJOBS_RUN_ID - The current run id of the job (used for triggered jobs).

Logging

For continuous WebJobs - Console.Out and Console.Error are routed to the "application logs", they will show up as file, blob or table storage depends on your configuration of the application logs (similar to your Website).

Also the first 100 lines in each invocation will also go to the WebJob log file (to ease debugging pain when the WebJob fails at startup) accessible using the Azure portal (but also saved on your site's file system at data/jobs/continuous/jobName).

For triggered WebJobs - Console.Out/Console.Error are routed to the WebJobs specific run log file also accessible using the Azure portal and stored at data/jobs/triggered/jobName/runId.

Console.Out is treated (marked) as INFO and Console.Error as ERROR.

Deployment

There are multiple ways to deploy WebJobs.

Using the Azure portal

From the portal, you can directly upload a zip file that contain the WebJob's files.

Copying files directly in their proper location

You can deploy a WebJob by directly copying the files under the locations discussed above (i.e. wwwroot/app_data/jobs/...). This can be done either by FTP, WebDeploy, Kudu Console or git.

Deploying .NET Console WebJobs alongside an ASP.NET application

If you have Visual Studio 2013 Update 3 (or later), it lets you do exactly this (more info here). Previously, this was done using the WebJobsVs VS add-in, but that is now obsolete.

High level:

  • You have both an ASP.NET app and one or more WebJobs (Console apps) in your solution
  • You ask the ASP.NET app to include the WebJobs apps with itself when deploying

This works both when deploying directly from Visual Studio (WebDeploy), or via git.

Graceful Shutdown

Graceful shutdown is the ability to notify the job process that it's going to shutdown and a wait period for the process to go down by itself before killing it.

The shutdown can happen on this cases: the site is getting stopped/restarted, the job is getting stopped, the app settings configuration (of the site) is changed, web.config is updated, the job binaries are updated.

The graceful shutdown feature works slightly different for continuous and triggered jobs:

Continuous

When a shutdown request is detected a file will be created in the path: %WEBJOBS_SHUTDOWN_FILE% (environment variable which can be obtained by the job's process).

Then there is a default period of 5 seconds waiting for the job process to shutdown before getting killed.

Triggered

When a shutdown request is detected there is a 30 seconds default waiting period for the job process to stop.

You can change the grace period of a job by specifying it (in seconds) in the settings.job file (should be in the same root directory as the job's script) where the name of the setting is stopping_wait_time like so:

{ "stopping_wait_time": 60 }

this sample will have the job grace period at 60 seconds instead of the default.

API

WebJobs API