Overview

This repository is home to a collection of templates used development tools to provide a quick start experience for Azure Functions. A template in this context is a sample function that demonstrates use of one or more bindings supported by Azure Functions. Here are the development tools that use templates from this repository:

• Azure Function Core Tools
• Azure Portal
• Visual Studio Code
• Visual Studio

Build Status

Branch	Status
dev
master
v3.x
v1.x

Getting Started

This section is focused on building templates for Azure Functions. If you are not familiar with Azure Functions, please refer to the following documentation to learn about technical concepts and components surrounding Azure Functions.

• Azure Functions overview
• Azure Functions developers guide

Repository Structure

root
|
└─── Functions.Templates
|    |
|    └─── Templates
|    |
|    └─── ProjectTemplate
|    |
|    └─── Resources
|    |
|    └─── Bindings
└─── Tools
|    |
|    └─── CheckResourceStrings
|  
└───Build

Requirements

• Node (10.x)
• Gulp

Build Steps

cd Build
npm install
gulp build-all

These build steps only work on Windows

Template files

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. You can find information on the metadata files in the section below:

• 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 example TimerTriggerCSharp_description is present in resources.resx file and is referenced in metadata.json file as $TimerTriggerCSharp_description

• Sample.dat: Sample.dat contains sample input data for each template.

• 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"
      ]
  }

• 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.

  {
    "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
            }
          ]
        }
      ]
  }

Adding a new template

1. At the minimum, following three files are required for it to be a valid template.
   • function.json
   • metadata.json
   • run
2. Add the following entries to this nuspec file

<file src="Templates/<TemplateFolderName>/<CodeFileName>" target="Templates/<TemplateFolderName>/run.<ext>" />
<file src="Templates/<TemplateFolderName>/function.json" target="Templates/<TemplateFolderName>/function.json" />
<file src="Templates/<TemplateFolderName>/metadata.json" target="Templates/<TemplateFolderName>/metadata.json" />
<file src="Templates/<TemplateFolderName>/sample.dat" target="Templates/<TemplateFolderName>/sample.dat" />

3. Make sure the strings present in metadata.json are added to the Resource file. Strings are reference by adding '$' before the string name. For example $TimerTriggerCSharp_description present in the metadata.json

Adding dotnet templates

Dotnet used in Visual studio are driven by dotnet templating engine. Follow this documentation to learn how to create dotnet templates. You can find more information on the templating engine at the wiki page of the dotnet templating repository.

• After you have created a dotnet template, Add the file entries to the ItemTemplates nuspec file.

Adding templates to extension bundle

1. Follow the steps mentioned in the adding a new template section.
2. Add the file entries to the ExtensionBundleTemplates-1.x nuspec file or ExtensionBundleTemplates-2.x nuspec file depending on your requirement.

Testing templates

Azure Function Core Tools

1. Once the template files have been added / updated, build the templates using the Build Steps
2. Locate the built templates at ..\bin\Templates
3. Locate the install location of core tools by executing where func from command line.
4. Locate the templates directory typically present here nodejs\node_modules\azure-functions-core-tools\bin\templates
5. Replace the contents of the templates directory with the one found in Step 4.
6. Create a new function app using func init . --no-bundle
7. Select non-dotnet runtime

Visual Studio

1. Once the template files have been added / updated, build the templates using the Build Steps
2. Make sure all instances of Visual Studio are closed
3. Open the LastKnownGood found at %userprofile%\AppData\Local\AzureFunctionsTools\Tags\v2
4. Note the release version present in the file
5. Open the templates folder %userprofile%\AppData\Local\AzureFunctionsTools\Releases\<releaseVersion>\templates matching the release version found in step 2. (Note: if adding the files to the release version folder found in LastKnownGood doesn't work, then try other release version folders.)
6. Replace the contents of the folder with the one found in ..\bin\VS
7. Rename Microsoft.Azure.WebJobs.ItemTemplates.X.0.0.nupkg to ItemTemplates.nupkg
8. Delete the %userprofile%\.templateengine directory
9. Select Azure Functions v2 (.NET Core) when creating a new function app via Visual Studio

Extension bundle template via Azure Function Core Tools

1. Once the template files have been added / updated, build the templates using the Build Steps
2. Locate the built templates at ..\bin\ExtensionBundle.Templates-v2
3. Replace the contents of the StaticContent\v1 directory for the bundle you want to test
   • Sample Location: %userprofile%\AppData\Local\Temp\Functions\ExtensionBundles\Microsoft.Azure.Functions.ExtensionBundle\2.0.1\StaticContent\v1
4. Create a new function app using func init . (If you are testing .csx files then run func init . --csx)
5. Create a new function using func new (If you are testing .csx files then run func new --csx)
6. Start a function app by running func host start or func start

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 [email protected] 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.