Home

Overview

Please see the ReadMe for an overview of this project.

The main concept in this library is the ScriptHost. The ScriptHost is responsible for loading one or more function script files (either Node.js or C# files) along with a companion function.json metadata file, and bootstrapping those functions into a running Azure WebJobs SDK JobHost. Global host configuration options are specified in a host.json metadata file in the root of the scripts directory.

If you're familiar with JobHost and its use in a continuous WebJob console app, the hosting model for ScriptHost will very familiar (ScriptHost is a subclass of JobHost):

static void Main(string[] args)
{
    ScriptHostConfiguration config = new ScriptHostConfiguration()
    {
        // path to root function script directory
        RootPath = Environment.CurrentDirectory
    };
    ScriptHost host = ScriptHost.Create(config);
    host.RunAndBlock();
}

The ScriptHost expects a certain file layout. There should be an individual folder per function containing all the scripts and metadata for the function. Function folders can contain a single script, or multiple scripts (e.g. if the function is a Node module, includes companion files that it loads, etc.) Each function folder should also include a function.json metadata file describing the function, how it should be triggered, etc. See the sample referenced below for an example scripts directory.

Samples

In the sample directory there are example functions that can be run to see things in action. For some of the script types, there is additional configuration needed if you want to be able to run them locally. In Azure, all of the script types will run automatically.

Since our test matrix is very large with all the various script languages we support, it's unfortunately a chore to install all the things required to run all the end to end tests successfully. If you're going to be committing code you'll need to ultimately do this, but there are shortcuts (see below) if you just want to be able run a subset of the samples/languages.

First, here are the things you need to set up to run everything:

• Select a language: Add a system environment variable named FUNCTIONS_WORKER_RUNTIME
  • Set value to dotnet to run CSharp/Fsharp/Precompiled samples
  • Set value to node to run JavaScript samples
  • Set value to java to run Java samples
  • Set value to python to run Python samples
• Dashboard: Add AzureWebJobsStorage and AzureWebJobsDashboard with your storage account connection string
• BASH: Add a system environment variable named AzureWebJobs_BashPath that points to the directory containing bash.exe. If you have GitHub for Windows installed, it should be in that bin dir (For reference, the bash version on Azure is 4.3.42(5)-release earlier version may not work)
• Python: To run Python functions, install Python and add it to your PATH environment variable. Install the latest 3.x version (you can download from https://www.python.org/downloads/windows/).
• PHP: To run PHP functions, install PHP and add it to your PATH environment variable. Install the Thread-safe version of PHP from http://windows.php.net/download/
• MobileTables: To run samples that use Mobile Tables, you will need to create a new Azure Mobile App and add an Item table with anonymous access (under "Easy tables"). Then add an AzureWebJobsMobileAppUri and AzureWebJobs_TestMobileUri environment variables that contain the URI of your Mobile App.
• DocumentDB: To run samples that use DocumentDB, create a DocumentDB account. Then add an AzureWebJobsDocumentDBConnectionString environment variable with the connection string to your account. This can be found in the Azure portal. The DocumentDB E2E tests will automatically create a new database and collection for you. The samples will not. You can either change createIfNotExists to true in those samples or manually create the ItemDb database and ItemCollection collection in your DocumentDB account.
• EventHubs To run samples that use EventHubs, create an event hub namespace and event hub following the steps here: https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-create. Under the event hub namespace's "Settings", go to "Shared access policies" and create a new policy with "Manage, Send, Listen" claims. Then, add the following environment variables
  • AzureWebJobsEventHubSender: Environment variable with the connection string from your newly generated policy.
  • AzureWebJobsEventHubReceiver: Same as above.
  • AzureWebJobsEventHubPath: The name of your event hub entity (example: testhub).
• NotificationHub: To run the NotificationHub samples, create an Azure Mobile App and set it up for push notifications following instructions at: https://azure.microsoft.com/en-us/documentation/articles/app-service-mobile-windows-store-dotnet-get-started-push/, then add following environment variables
  • AzureWebJobsNotificationHubsConnectionString: Environment variable with the connection string to your NotificationHubs. Same as MS_NotificationHubConnectionString. This can be found in the Azure portal MobileApp's Application settings.
  • AzureWebJobsNotificationHubName: Environment variable with the name of your NotificationHub. Same as MS_NotificationHubName. This can be found in the Azure portal Mobile App's Application settings.
• Dropbox: Add AzureWebJobsDropBox with UseLocalFileSystem=true;Path=C:\Users\<user>\AppData\Local\Temp\DropBox
• ServiceBus: Add AzureWebJobsServiceBus with your service bus connection string

When running the samples you'll see output in the Console window, but it's recommended that you also open the WebJobs Dashboard to view your invocations. You can also use the Dashboard to replay/run functions, etc. To run the samples, you can use WebJobs.Script.Host or WebJobs.Script.WebHost. WebJobs.Script.WebHost is useful if you want to test WebHook samples (more details below).

• To use samples with WebJobs.Script.Host as the startup project:

  • Make sure you've set up your AzureWebJobsStorage and AzureWebJobsDashboard connection strings either as app.config connection strings, or as environment variables
  • The ServiceBus sample also requires you to configure your AzureWebJobsServiceBus connection string
  • Point the host to the sample script directory by opening the project settings and in the Debug"Start Options" section add the command line argument ..\..\..\..\sample
  • F5 to run

• To use samples with WebJobs.Script.WebHost as the startup project:

  • Set the AzureWebJobsScriptRoot environment variable to the full path to the function samples directory.
  • Set any necessary environment variables to run your sample functions (see above).
  • F5 to run

If you don't want to set up all the languages, you can do one of the following:

• Change the sample script directory to point to a script directory of your choosing, which can have just the functions you want to run. Do this by setting the Debug"Start Options" option as detailed above, just point to your folder.
• You can also constrain the set of samples to run via the host.json file. For example if you add a property functions: [ "QueueTrigger" ] it will only initialize/run that single function. You can add an array of functions to run here, omitting any you don't want.

The sample includes a timer based scheduled job, so you will see the functions running and producing output in the console window and WebJobs Dashboard. The sample also includes Queue/Blob/WebHook functions that you can also trigger. Details on a few of the samples below.

• TimerTrigger - A Node.js function that is triggered every minute (via CRON expression 0 * * * * *). Every minute, this function enqueues a message to queue samples-fsharp which in turn triggers _that _function to run.
• QueueTrigger - A Node.js function that is triggered on queue messages added to samples-workitems. Create this queue and add a message in the format { "id": 12345, "category": "Maintenance", "description": "Change the light bulb" }. The function will write the message to an output blob at path samples-workitems/{id} (where {id} is the id value of the message.
• BlobTrigger - A Node.js function that is triggered on new blobs written to container samples-workitems. You can try this by writing a blob yourself. However, the above QueueTrigger function also writes its output to this container, so these functions are chained.
• QueueTrigger-Batch - A Windows batch script that is triggered on queue messages written to samples-batch and writes the messages as output blobs to the samples-output container. It uses the same message format as above (expects an id property).
• ResizeImage - A full end to end example demonstrating a Windows Batch script that is triggered when images are added to blob container images-original. The function resizes the image (using a companion exe), and writes the resulting resized image to blob container images-resized. The output binding binds to the name of the input blob and uses the same name for the resized image blob.

Build / Test Locally

You can run and test Azure Functions locally by running the WebJobs.Script.WebHost project. It is recommended that you use Visual Studio and add the following environment variables (or properties):

• AZURE_FUNCTIONS_ENVIRONMENT
  • Value: Development
  • Meaning: Shows console logging
• AzureWebJobsScriptRoot
  • Value: Path to directory with the targeted Function App (the directory with host.json)
  • Meaning: This is the Function App that you want to run

Build / Test in Azure

Prerequisite: first go through the previous section about getting set up to run samples.

To build everything, run the tests, and produce the output packages (Nugets and Zips), you can just use VS, or you can run msbuild WebJobs.Script.proj from the root (ideally from an admin VS Developer Command Prompt). Outputs will be copied to the bin dir.

Deployment

⚠️ Trying to deploy Azure Functions V1 and beyond? Follow instructions on deploying the Functions runtime as a private site extension instead.

The Azure deployment model for ScriptHost is a work in progress. Eventually the ScriptHost will be installed automatically on all Azure WebApp workers, so you'll only need to deploy your scripts. However, for now, in addition to your scripts, you also have to deploy the ScriptHost binaries. There are two options for how you can deploy things, depending on whether you want HTTP function/WebHooks support, or just want to run standard WebJobs SDK type functions (e.g. Queue triggered functions, etc.) You can use Kudu or FTP to do the below deploy operations. In both cases, you'll want to enable AlwaysOn on your site.

You can get the Functions.Private.zip/WebJobs.Script.Host.zip packages referenced below from the latest release here.

Option 1 (HTTP Function/WebHook support)

If you want HTTP function support (in addition to other triggered functions) then follow these steps. The high level here is that you'll be adding the ScriptHost runtime as a private site extension to your site. This site extension is an HTTP head that will accept and authenticate incoming requests before dispatching them to your functions. It maintains a ScriptHost instance internally which it keeps alive to process non HTTP functions. Your Function script files will be deployed to your WWWW root.

1. Add your AzureWebJobsStorage/AzureWebJobsDashboard connection strings in the Ibiza portal AppSettings section of your WebApp host
2. Create a new folder D:\HOME\SiteExtensions in your site
3. Use Kudu Drag/Drop (or FTP) to deploy the Functions.Private.zip package to that directory. In Kudu, drag the zip into D:\HOME and it will unzip things properly. You should be left with a folder D:\HOME\SiteExtensions\Functions
4. Restart the site so the site extension is picked up
5. In your wwww root (D:\HOME\SITE\WWWROOT) add your host.json and Function folders. Your script layout should follow the pattern shown in the sample
6. For HTTP functions, you'll need to add secret files (containing security keys used for securing your functions) to D:\home\data\Functions\secrets. See the example here in the repo. See the HTTP function example below which shows how a key is passed as a query string param.
7. Now that you've configured everything, to test it out you can deploy the HttpTrigger sample to your site. Just copy it in to the live site. You'll then be able to invoke your function via a URL like: http://<your-site>.azurewebsites.net/api/httptrigger?key=9b70f4005c5c7fda292c138fba8cb8a4b3072acc

The following image shows an example of what your directory should look like (this is a screen shot of my D:\home\site\wwwroot dir):

Option 2 (No HTTP Function/WebHook Support)

If you don't want HTTP function support, then you can deploy the ScriptHost as a regular continuous WebJob as you would for a normal WebJobs SDK job. Here are the steps:

1. Add your AzureWebJobsStorage/AzureWebJobsDashboard connection strings in the Ibiza portal AppSettings section of your WebApp host
2. In your continuous WebJob folder (e.g. D:\home\site\wwwroot\app_data\jobs\continuous\ScriptHost) add your host.json and Function folders. Your script layout should follow the pattern shown in the sample
3. To the same continuous WebJob folder above, add a bin directory containing the WebJobs.Script.Host binaries. These binaries are in the WebJobs.Script.Host.zip file.
4. A run.cmd file in the WebJob folder (peer to the bin dir) that invokes WebJobs.Script.Host.exe. The run file should contain the line .\bin\Microsoft.Azure.WebJobs.Script.Host.exe. When the WebJob starts, this will be the entry point, the ScriptHost will start up, load all the function scripts and begin running your functions. After this, if you look at the Process explorer in Kudu you should see something like this (notice the cmd process labeled "webjob"):
5. (Optional) If your functions only include script files and no binary files that might get loaded/locked, you can increase your startup performance by disabling shadow copy. More on this in the notes below.

The following image shows an example of what your directory should look like (this is a screen shot of my D:\home\site\wwwroot\app_data\jobs\continuous\ScriptHost dir):

Notes:

• After constructing a job directory as above, you can run it locally before deploying it to Azure. If you start the ScriptHost locally, it will open a Console window showing the normal WebJobs SDK output.
• If you are running Node.js functions and you have large NPM trees, or in general if your function content is all just script files (i.e. no binaries that might get loaded and locked), you can increase startup performance by disabling shadow copy of the job files. You can do this by placing a settings.job file next to your run.cmd file, with the content: { "is_in_place": true }. More details on this in the Kudu wiki here.

Getting Help

• Azure Functions Documentation
• Azure Functions MSDN Forum
• Azure Functions on Stack Overflow