Setting up a local dev environment for Azure Functions
Update 1st December 2016: If you want an easier route there’s now integrated tooling available:
https://contos.io/real-tooling-for-azure-functions-in-visual-studio-3ed5a6095436#.ph1rbwyuhUpdate August 9th: There is a new approach in preview (Azure Functions CLI Node Module) that should be checked out:
https://contos.io/azure-functions-cli-quick-start-ee843dfbe72c?source=latest
The approach below is still valid, so you could read about them both and see what you prefer.
While Azure Functions are powerful in this first incarnation it is a slightly disjointed developer experience at the moment.
The easy way to get started is writing code directly in the Azure Portal. You can type away, compile through the browser, and run directly in the browser. Basically you can do everything in the browser without ever opening any dev tools locally. This is great when you’re just looking to write down some simple lines of code. One pain point to note is that you don’t get IntelliSense, and if you’ve gotten used to this feature, (most Visual Studio users would), coding without it is virtually hopeless :) You work on each Function individually, and you don’t get to see “the bigger picture” if you have multiple functions and/or classes in a Function App. You might also find it somewhat limiting that the frame you type your code into doesn’t take advantage of all of the screen real estate you have available, thus requiring extra scrolling compared to a full-screen editor.
You can get around this by flowing your code through Git instead of the Azure Portal. You can use your normal tools locally, commit to a repo, and have it pulled in and deployed by Azure Functions through Continuous Integration. This way you get IntelliSense and don’t have to use the browser at all. At the other end of the spectrum compared to working in the Azure Portal basically. But the Function still needs to run in Azure, so actually debugging this requires hooking up your editor to the cloud. As a measure to prevent code being out of sync you can’t edit it in the Azure Portal anymore if the code is under source control. Making it a somewhat binary choice between the portal and no portal. (You could deploy through FTP to work around this “lock”.)
While you could say that these aren’t showstoppers, you might find yourself wanting to develop things locally to work around limitations like these. I decided to take a shot at setting up something on my computer to see where I could take things in the absence of official tooling and support in Visual Studio. (Tooling is being worked on, but the service is in preview so things just aren’t entirely prime-time yet.)
Luckily you don’t have to build it all from scratch since Azure loves open-source :)
First thing to do is to download the WebJobs Script SDK from GitHub:
https://github.com/Azure/azure-webjobs-sdk-script
After I had extracted the files and started to work on the solution in Visual Studio I found an official guide to actually get it running on your own box:
https://azure.microsoft.com/en-us/documentation/articles/functions-run-local/
This guide has all the steps needed to get everything going, and you should read it or at least skim through it. For my test case I didn’t need everything wired up since I just wanted to test simple C#-based HTTP-triggered functions for now. To get that working you can ignore most of the instructions and just make sure that the WebHost looks in the right place for your .csx files.
The recommendation would be to set the AzureWebJobsScriptRoot environment variable as described. If you want to go quick and dirty you can set this path directly in the code as well.
Locate root\src\WebJobs.Script.WebHost\App_Start\WebApiConfig.cs, and insert a path of your choosing in the setting.ScriptPath variable:
As you can see I created my own folder called “myFunctions”, but if you want to play with the provided templates those are located in the samples subfolder.
If you don’t require more features you can just set the WebJobs.Script.WebHost project as the “StartUp Project” and hit F5. This will give you the Functions “engine” running, but no UI for input/output and control.
The code for the Functions themselves needs to be wrangled separately in other words. If you’re looking for the slimmed down experience you could write the code in Visual Studio Code:
Or use Visual Studio 2015 for the classic “C# good times”:
Personally I switch between the two depending on what I’m trying to do. Both will work of course. As will Notepad for that matter, but that’s probably not something you would want to :)
Word of advise before testing. Make sure your folder structure is correctly configured before moving on or you will see HTTP errors returned.
This is explained in the MSFT doc linked to, but I’m re-iterating it here:
1. In the root folder (“myFunctions”) place a host.json file that has the names of the folders below it specified:
{
“functions” : [“Proto”, “HelloWorld”],
“id”: “5a709861cab44e68bfed5d2c2fe7fc0c”
}2. Make sure there is a function.json in the folder containing the trigger specifications:
{
“bindings”: [
{
“type”: “httpTrigger”,
“direction”: “in”,
“methods”: [ “get” ]
},
{
“type”: “http”,
“direction”: “out”
}
]
}3. If you want to use external assemblies create a subfolder called /bin and drop the dlls there. In the code these are referenced like this (without referring to the subfolder):
#r “myassembly.dll”4. Put the actual Function in a file called run.csx (in the same folder as function.json) and save it.
Now things should be setup for execution. The Azure Portal has a nice “Run” button to allow you to test it out, but you don’t have that here. The easiest thing to do, is to open another browser tab, or Fiddler, and execute an HTTP GET:
Wait up, where did that cryptic code parameter in the query string come from? If you open the \App_Data\secrets\host.json file you will notice that the value can be found in the “functionKey” key. This is used as an authentication mechanism. You can set up individual keys for different functions (advisable in production), but you can make it easier in dev mode either by using one key for all functions, or disabling it altogether by adding an extra parameter to the function.json file (authLevel anonymous):
This simplifies the url accordingly:
http://localhost:28549/api/HelloWorld?name=Andreas
Whether you’re just testing things locally like here, or moving to production, authentication is a big topic in it’s own right so you should probably take a brief pause and reflect on that. If you know the ins and outs of OAuth you can ignore me, and follow your own instincts :) I touched briefly on one possible auth scenario here:
Working with identity in an Azure Function
Did I mention Azure Functions can be quite neat?
medium.com
If you set up your code and browser/Fiddler side by side you can get a decent setup for hacking out those Azure Functions locally. The debug experience might not be what you want yet though:
The exception is thrown when you trigger the function since I haven’t setup any compilation of the script at save time. You might want to pay attention to this, but as you long as write code without bugs you should be fine :)
To loop back and come full circle — what if you happen to like browser editing as provided by the Azure portal? Well, technically there’s nothing preventing you from building your own UI for that:
Type your code in the top frame. Once you click “Save” the code is saved into a .csx, and the HTTP trigger for the Function is invoked. This kicks off the compilation of the script, and the output from the Function is displayed in the lower frame. (WebHost running in one Visual Studio debug session, and a separate Web App for the UI in Visual Studio instance number two.)
Granted, this doesn’t look very good, and it leaves you with less features than you started with in the cloud. (No syntax highlighting, and still no IntelliSense.) The Azure Portal delivers a richer UI than this, but there’s nothing stopping you from being more creative than me and build out exactly the experience you want locally. Want to build a native app specifically for this purpose? You can do that. Have other tools, editors and build chains that you want to use? Go ahead and plug them in.
Taking it a step further you could deploy the WebHost to a Docker container or something, and just have it totally in the background while focusing on writing the scripts.
Word of caution:
Scripts like these are flexible, but you obviously don’t want random people writing malicious code and executing it on your box, so use this setup only for local dev work. The Azure Portal brings in other features, not present here, in the background for isolating the parts of it preventing you from messing up more than you should.
As stated earlier, tooling will probably come to Visual Studio in one form or the other. MSFT will probably (and hopefully) make this a bit more polished than what I have here. They might take things in a whole different direction than what I have focused on — maybe a webhook written in Node needs an entirely different setup than this quick hack. Think of this walkthrough as just a simple exploration of an isolated part of the possibilities offered by the WebJobs Script SDK.
