Overview
This repository is home to a collection of templates used by development tools to provide a quick start experience for Azure Functions. A template in this context is a sample that demonstrates use of one or more bindings supported by Azure Functions. Following are the development tools that use templates from this repository:
Dotnet templates are consumed by Visual Studio and Visual Studio code via tooling feed. Non-dotnet and C# Script templates are consumed via extension bundles.
Build Status
Branch | Status | Description |
---|---|---|
dev | This is the primary development branch all pull request go against this branch. | |
master | This is the deployment branch all releases are performed from this branch. |
Build Requirements
Build Steps
cd Build
npm install
gulp build-all
These build steps only work on Windows
Dotnet templates
There are two kind of dotnet templates contained within this repository, script type (.csx and .fsx) templates that do not require compilation and non-script type (.cs and .fs) templates that require compilation.
Creating a dotnet templates (.cs and .fs)
Template for dotnet precompiled functions apps adheres to the specification provided by the dotnet templating engine. The dotnet templating engine or an implementation of one is present within each of the dotnet client and is responsible for consuming dotnet templates. This format is not specific to Azure Functions but is a standard used for all dotnet templates by VS, VS Code and dotnet cli. This section covers some basic information needed to add a pre-compiled template.
There are 2 kinds of dotnet templates.
- Project templates: Project templates are responsible for creating initial set of files needed to build and run the project. For azure functions this would include, csproj file, host.json, local.settings.json file and so on.
- Item templates: Item templates are templates include files that you would want to add to an existing project. For azure functions this would mean class files, new functions.
Template files:
At the minimum you need the following files for a valid dotnet template. Please refer to the this link for detailed documentation on each of the files and properties contained within the file.
- .template.config/template.json : Presence of this file within the folder structure indicates to the dotnet templating engine that this is a template. This file contains symbols and post action action configuration that is used to generate a function from the template. The key difference between project and item template file is that
tags -> type
property would say project vs item for corresponding template types. Below is sample file with comments on individual fields. - .template.config/vs-2017.3.host : This file contains information required to generate UI elements in Visual studio. For example, label and help text for UI elements.
- .template.config/vs-2017.3/*.png: Icon files for menu items in Visual studio.
- Class file or Project file : Class file is required if you are creating an item template. This could be either a
.cs
file or a.fs
file. Project file is require if you are creating a project template. This could be either a.csproj
file or an.fsproj
file.
Here is a sample PR adding a dotnet item template. Azure#1162
Adding a dotnet template for release to Visual Studio / Visual Studio code
This section covers information you need to add your template to the list of templates that show up within Visual studio and Visual studio code. VS and VS code only support templates for a single major version of a particular extension. That means there currently is no way to simultaneously include templates that target different major versions of the same extension within the same template list. The build system in this repository uses .nuspec files
to manage different release trains. Add your template to the nuspec file corresponding to the target runtime release based on the table below.
Nuspec File | Description |
---|---|
ProjectTemplates_v3.x.nuspec | Project templates for dotnet in-proc function app targeting runtime v3 |
ItemTemplates_v3.x.nuspec | Item templates for dotnet in-proc function app targeting runtime v3 |
ProjectTemplates-Isolated_v3.x.nuspec | Project templates for dotnet isolated (out of proc) function app targeting runtime v3 |
ItemTemplates-Isolated_v3.x.nuspec | Item templates for dotnet isolated (out of proc) function app targeting runtime v3 |
ProjectTemplates_v4.x.nuspec | Project templates for dotnet in-proc function app targeting runtime v4 |
ItemTemplates_v4.x.nuspec | Item templates for dotnet in-proc function app targeting runtime v4 |
ProjectTemplates-Isolated_v4.x.nuspec | Project templates for dotnet isolated (out of proc) function app targeting runtime v4 |
ItemTemplates-Isolated_v4.x.nuspec | Item templates for dotnet isolated (out of proc) function app targeting runtime v4 |
Testing dotnet templates
Dotnet pre-compiled templates are currently hosted by the following clients. Please follow the instructions in this section to test the corresponding clients.
-
Visual Studio (VS 2019 and VS 2022):
- Once the template files have been added / updated, build the templates using the Build Steps
- Make sure all instances of Visual Studio are closed;
- Open the directory
%userprofile%\AppData\Local\AzureFunctionsTools\Tags
- Each of the directory within the tags directory represent a runtime, for testing runtime v4 templates open directory v4
- Open the
LastKnownGood
in v4 (runtime version templates you want to test) directory, Note the release version present in the file - For in-proc templates
- Open the templates output directory,
..\bin\VS
and renameMicrosoft.Azure.WebJobs.ItemTemplates.X.0.0.nupkg
toItemTemplates.nupkg
,Microsoft.Azure.WebJobs.ProjectTemplates.X.0.0.nupkg
toProjectTemplates.nupkg
- Open the templates cache directory
%userprofile%\AppData\Local\AzureFunctionsTools\Releases\<releaseVersion>\templates
for release version matching the one found in step 5. - Replace the contents of the folder with the renamed package found in
..\bin\VS
- Open the templates output directory,
- For testing net5-isolated templates, repeat the step 6, replace the contents of net5-isolated with
Microsoft.Azure.Functions.Worker.ItemTemplates.3.x.x
. Same for the corresponding project template - For testing net6-isolated templates, repeat the step 6, replace the contents of net5-isolated with
Microsoft.Azure.Functions.Worker.ItemTemplates.4.x.x
. Same for the corresponding project template - Delete the
%userprofile%\.templateengine
directory - Select corresponding function runtime when creating a new function app via Visual Studio
- Run through the test scenarios
-
Core tools:
- Once the template files have been added / updated, build the templates using the Build Steps
- Find the location of core tools installation,you can use the command
where func
from windows command prompt - Locate the
bin\tempaltes
directory relative toazure-functions-core-tools
at install location - For in-proc templates
- Open the templates output directory,
..\bin\VS
and renameMicrosoft.Azure.WebJobs.ItemTemplates.X.0.0.nupkg
toItemTemplates.[version].nupkg
,Microsoft.Azure.WebJobs.ProjectTemplates.X.0.0.nupkg
toProjectTemplates.[version].nupkg
. Use the version from templates found in step 3. - Open the templates cache directory
%userprofile%\AppData\Local\AzureFunctionsTools\Releases\<releaseVersion>\templates
for release version matching the one found in step 5. - Replace the contents of the folder with the renamed package found in
..\bin\VS
- Open the templates output directory,
- For testing net5-isolated templates, repeat the step 3, replace the contents of net5-isolated with
Microsoft.Azure.Functions.Worker.ItemTemplates.3.x.x
. Same for the corresponding project template - Delete the
%userprofile%\.templateengine
directory
-
Visual Studio Code: We currently do not have a way to test templates in VS code without going to through extensive set up. Will update this section with instructions once we have the right set of hooks enabled.
Creating script type templates
Script type templates are templates for functions that do not require a compilation step. The templates includes metadata files in addition to the files required to execute a function. The metadata files help drive the user interface and development experience for creating a function using a template. In addition to the metadata file you would also need to add a code file for the corresponding language in the template. You can find information on the metadata files in the section below:
Template files:
-
Code file: This is the file that contains the function execution code. This could be Python, JavaScript (Node JS), PowerShell, CSharp Script, FSharp Script. The only time this file is not needed is when you are creating a template for custom handlers.
-
Metadata.json: This file includes basic information that explains the purpose of the template. It also includes configuration properties that help drive the UI required to create a function using a template. Individual properties are explain inline.
{
"defaultFunctionName": "TimerTrigger", // Default name to be used for a function if the user does not provide one during deployment.
"description": "$TimerTrigger_description", // Short description explaining the functionality of the generated function.
"name": "Timer trigger", // The template name shown in UI.
"language": "C#",
"category": [ // Category under which this template should be presented.
"$temp_category_core",
"$temp_category_dataProcessing"
],
"categoryStyle": "timer", // Category style used to pick the correct icon for the template.
"enabledInTryMode": true, // Should this template be available in try mode: https://tryfunctions.com/ng-min/try?trial=true
"userPrompt": [ // The development tools will prompt to configure this setting during template deployment
"schedule"
]
}
-
Resources.resx: This file contains all the localized resource strings referenced in the metadata files. The strings are used for description, help, error text and other display text for the UI elements of the development tools. Strings in resources.resx file are reference by adding
$
before the corresponding string name. For exampleTimerTriggerCSharp_description
is present in resources.resx file and is referenced in metadata.json file as$TimerTriggerCSharp_description
-
Bindings.json: This file contains metadata for all the configuration options available for all the bindings. This allows the development tools to provide the users with an option to configure additional settings for the bindings used by the template. It also drives to UI used to add / modify bindings of an existing functions. Here is a sample entry for timerTrigger binding. You only need to add a template for binding that does not exist in binding.json.
{
"type": "timerTrigger", // The binding type property matching the "type" property in function.json
"displayName": "$timerTrigger_displayName", // This is the text used by the UI element to display binding name.
"direction": "trigger",
"enabledInTryMode": true, // Should this binding be available in try mode https://tryfunctions.com/ng-min/try?trial=true
"documentation": "$content=Documentation\\timerTrigger.md", // Location of the documentation related to this binding in the templates repository
"settings": [
{
"name": "schedule",
"value": "string",
"defaultValue": "0 * * * * *",
"required": true,
"label": "$timerTrigger_schedule_label", // display text for the config option
"help": "$timerTrigger_schedule_help", // help text explaining what the config option is
"validators": [
{
"expression": "", // regex that can be used to validate the configuration value
"errorText": "$timerTrigger_schedule_errorText" // help text in case the regex validation fails
}
]
}
]
}
- Sample.dat: Sample.dat contains sample input data for each template.
Adding a template to Extension bundle
Pretty much all non-dotnet templates do not require compilation. The only exception to this is java templates which are not part of this repository as of now. Non-dotnet templates, CSharp and FSharp script templates are deployed via Extension bundles. This means that a new version of these templates would be deployed when a new version of extension bundle is released. Similar to dotnet templates we use .nuspec files to control which templates are included in which package (in this case extension bundle). Following tables list all the .nuspec files and their corresponding bundles.
Nuspec File | Description |
---|---|
ExtensionBundleTemplates-1.x.nuspec | Templates for Extension bundle v1 |
ExtensionBundleTemplates-2.x.nuspec | Templates for Extension bundle v2 |
ExtensionBundleTemplates-3.x.nuspec | Templates for Extension bundle v3 |
ExtensionBundlePreviewTemplates-3.x.nuspec | Templates for preview Extension bundle v3 |
ExtensionBundlePreviewTemplates-4.x.nuspec | Templates for preview Extension bundle v4 |
Testing script type template via Core tools
- Once the template files have been added / updated, build the templates using the Build Steps
- Locate the zip file for built template in the bin directory
..\bin\
- Extract the zip file content you want to test. This be based on the nuspec file you updated.
- Create a function app via core tools, open host.json to verify that it has extension bundle configuration present.
- Sample commands for node app:
func init . --worker-runtime node
- Sample commands for node app:
- Execute the
func GetExtensionBundlePath
to find the path to the bundle being used.- Sample response:
%userprofile%\.azure-functions-core-tools\Functions\ExtensionBundles\Microsoft.Azure.Functions.ExtensionBundle\2.8.4
- Sample response:
- Replace the contents of the
StaticContent\v1
directory (path from step 5) with the files extracted from the zip file in step 3. - Execute
func new
at the root of the sample app to see the new / updated templates.
License
This project is under the benevolent umbrella of the .NET Foundation and is licensed under the MIT License
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Related Github Repositories
- Azure Function Core Tools
- Azure Portal
- Visual Studio Code
- Azure Function Host
- WebJobs SDK Extensions
Contribute Code or Provide Feedback
If you would like to become an active contributor to this project please follow the instructions provided in Microsoft Azure Projects Contribution Guidelines. If you encounter any bugs with the templates please file an issue in the Issues section of the project.