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 be 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

Extension bundle configuration

If the function app being used as part of the debugging setup is configured to used extension bundles. You would need to configured the following 2 things.

1. Environment variable:
   • Name: FUNCTIONS_CORETOOLS_ENVIRONMENT
   • Value: true
   • Meaning: Configured to let function runtime know that it is running in the context of local development environment.
2. Host.json configuration:

      {
         "version": "2.0",
         "extensionBundle": {
            "id": "Microsoft.Azure.Functions.ExtensionBundle",
            "version": "[1.*, 2.0.0)", 
            "downloadPath": "<newDirectory>"
           }
       }
   

Build / Test in Azure

Follow instructions on deploying the Functions runtime as a private site extension.

Getting Help

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