-
Notifications
You must be signed in to change notification settings - Fork 442
Home
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.
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
totrue
in those samples or manually create theItemDb
database andItemCollection
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 propertyfunctions: [ "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 queuesamples-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 pathsamples-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 thesamples-output
container. It uses the same message format as above (expects anid
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 containerimages-resized
. The output binding binds to thename
of the input blob and uses the same name for the resized image blob.
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
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.
- Environment variable in the Host
launch.json
file:- Name: FUNCTIONS_CORETOOLS_ENVIRONMENT
- Value: true
- Meaning: Configured to let function runtime know that it is running in the context of local development environment.
-
host.json
configuration in your function app:{ "version": "2.0", "extensionBundle": { "id": "Microsoft.Azure.Functions.ExtensionBundle", "version": "[3.*, 4.0.0)", "downloadPath": "<newDirectory>" } }
newDirectory
can be any path on your local machine. A set of files will be generated in this path.
Follow instructions on deploying the Functions runtime as a private site extension.
- Configuration Settings
- function.json
- host.json
- host.json (v2)
- Http Functions
- Function Runtime Versioning
- Official Functions developers guide
- Host Health Monitor
- Managing Connections
- Renaming a Function
- Retrieving information about the currently running function
- Site Extension Resolution
- Linux Consumption Regions
- Using LinuxFxVersion for Linux Function apps
- Out-of-proc Cancellation Tokens
- Assembly Resolution in Azure Functions
- ILogger
- Precompiled functions
- Official Functions C# developer reference
- Contributor Onboarding
- Development Process
- Deploying the Functions runtime as a private site extension
- Authoring & Testing Language Extensions
- Bindings in out-of-proc
- Language Extensibility
- Worker Capabilities
- Investigating and reporting issues with timer triggered functions not firing
- Sharing Your Function App name privately
- Azure Functions CLI release notes [moved here]
- Function App Zipped Deployment [deprecated]