From 076985e3410e0dba5045b94674b80159c06c60ff Mon Sep 17 00:00:00 2001 From: Naren Soni Date: Wed, 30 Mar 2022 11:56:47 -0700 Subject: [PATCH] Updating Readme.md --- README.md | 198 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 103 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index dd6dfb4c3..943ae1784 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,20 @@ # 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: +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: - [Azure Function Core Tools](https://github.com/Azure/azure-functions-core-tools) - [Azure Portal](https://portal.azure.com) - [Visual Studio Code](https://code.visualstudio.com/) - [Visual Studio](https://visualstudio.microsoft.com/vs/) -## Build Status -|Branch|Status| -|---|---| -|dev|[![Build Status](https://azfunc.visualstudio.com/Azure%20Functions/_apis/build/status/Azure.azure-functions-templates?branchName=dev)](https://azfunc.visualstudio.com/Azure%20Functions/_build/latest?definitionId=43&branchName=dev) -|master|[![Build Status](https://azfunc.visualstudio.com/Azure%20Functions/_apis/build/status/Azure.azure-functions-templates?branchName=master)](https://azfunc.visualstudio.com/Azure%20Functions/_build/latest?definitionId=43&branchName=master) -|v3.x|[![Build Status](https://azfunc.visualstudio.com/Azure%20Functions/_apis/build/status/Azure.azure-functions-templates?branchName=master)](https://azfunc.visualstudio.com/Azure%20Functions/_build/latest?definitionId=43&branchName=v3.x) -|v1.x|[![Build status](https://ci.appveyor.com/api/projects/status/9u3okk4mruuwt4dl/branch/v1.x?svg=true)](https://ci.appveyor.com/project/appsvc/azure-webjobs-sdk-templates/branch/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](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview) - - [Azure Functions developers guide](https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference) - -## Repository Structure -``` -root -| -└─── Functions.Templates -| | -| └─── Templates -| | -| └─── ProjectTemplate -| | -| └─── Resources -| | -| └─── Bindings -└─── Tools -| | -| └─── CheckResourceStrings -| -└───Build -``` +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|[![Build Status](https://azfunc.visualstudio.com/Azure%20Functions/_apis/build/status/Azure.azure-functions-templates?branchName=dev)](https://azfunc.visualstudio.com/Azure%20Functions/_build/latest?definitionId=43&branchName=dev)| This is the primary development branch all pull request go against this branch. | +|master|[![Build Status](https://azfunc.visualstudio.com/Azure%20Functions/_apis/build/status/Azure.azure-functions-templates?branchName=master)](https://azfunc.visualstudio.com/Azure%20Functions/_build/latest?definitionId=43&branchName=master)| This is the deployment branch all releases are performed from this branch. | -## Requirements +## Build Requirements - [Node (10.x)](https://nodejs.org/dist/latest-v10.x/) - [Gulp](https://gulpjs.com/docs/en/getting-started/quick-start) @@ -50,17 +24,83 @@ 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: +## 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. +1. 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. +2. 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. -- **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` +### Template files: +At the minimum you need the following files for a valid dotnet template. Please refer to the this link for [detailed documentation](https://github.com/dotnet/templating/tree/main/docs) on each of the files and properties contained within the file. -- **Sample.dat:** Sample.dat contains sample input data for each template. +1. **.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. +2. **.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. +3. **.template.config/vs-2017.3/*.png**: Icon files for menu items in Visual studio. +4. **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. -- **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. +Here is a sample PR adding a dotnet item template. https://github.com/Azure/azure-functions-templates/pull/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](Build/PackageFiles/Dotnet_precompiled/ProjectTemplates_v3.x.nuspec) | Project templates for dotnet in-proc function app targeting runtime v3 | +|[ItemTemplates_v3.x.nuspec](Build/PackageFiles/Dotnet_precompiled/ItemTemplates_v3.x.nuspec) | Item templates for dotnet in-proc function app targeting runtime v3 | +|[ProjectTemplates-Isolated_v3.x.nuspec](Build/PackageFiles/Dotnet_precompiled/ProjectTemplates-Isolated_v3.x.nuspec) | Project templates for dotnet isolated (out of proc) function app targeting runtime v3 | +|[ItemTemplates-Isolated_v3.x.nuspec](Build/PackageFiles/Dotnet_precompiled/ItemTemplates-Isolated_v3.x.nuspec) | Item templates for dotnet isolated (out of proc) function app targeting runtime v3 | +|[ProjectTemplates_v4.x.nuspec](Build/PackageFiles/Dotnet_precompiled/ProjectTemplates_v4.x.nuspec) | Project templates for dotnet in-proc function app targeting runtime v4 | +|[ItemTemplates_v4.x.nuspec](Build/PackageFiles/Dotnet_precompiled/ItemTemplates_v4.x.nuspec) | Item templates for dotnet in-proc function app targeting runtime v4 | +|[ProjectTemplates-Isolated_v4.x.nuspec](Build/PackageFiles/Dotnet_precompiled/ProjectTemplates-Isolated_v4.x.nuspec) | Project templates for dotnet isolated (out of proc) function app targeting runtime v4 | +|[ItemTemplates-Isolated_v4.x.nuspec](Build/PackageFiles/Dotnet_precompiled/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. + +1. Visual Studio (VS 2019 and VS 2022): + 1. Once the template files have been added / updated, build the templates using the [Build Steps](#build-steps) + 2. Make sure all instances of Visual Studio are closed; + 3. Open the directory `%userprofile%\AppData\Local\AzureFunctionsTools\Tags` + 4. Each of the directory within the tags directory represent a runtime, for testing runtime v4 templates open directory v4 + 5. Open the `LastKnownGood` in v4 (runtime version templates you want to test) directory, Note the release version present in the file + 6. For in-proc templates + 1. Open the templates output directory, `..\bin\VS` and rename `Microsoft.Azure.WebJobs.ItemTemplates.X.0.0.nupkg` to `ItemTemplates.nupkg`, `Microsoft.Azure.WebJobs.ProjectTemplates.X.0.0.nupkg` to `ProjectTemplates.nupkg` + 2. Open the templates cache directory `%userprofile%\AppData\Local\AzureFunctionsTools\Releases\\templates` for release version matching the one found in step 5. + 3. Replace the contents of the folder with the renamed package found in `..\bin\VS` + 7. 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 + 8. 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 + 9. Delete the `%userprofile%\.templateengine` directory + 10. Select corresponding function runtime when creating a new function app via Visual Studio + 11. Run through the test scenarios + +2. Core tools: + 1. Once the template files have been added / updated, build the templates using the [Build Steps](#build-steps) + 2. Find the location of core tools installation,you can use the command `where func` from windows command prompt + 3. Locate the `bin\tempaltes` directory relative to `azure-functions-core-tools` at install location + 4. For in-proc templates + 1. Open the templates output directory, `..\bin\VS` and rename `Microsoft.Azure.WebJobs.ItemTemplates.X.0.0.nupkg` to `ItemTemplates.[version].nupkg`, `Microsoft.Azure.WebJobs.ProjectTemplates.X.0.0.nupkg` to `ProjectTemplates.[version].nupkg`. Use the version from templates found in step 3. + 2. Open the templates cache directory `%userprofile%\AppData\Local\AzureFunctionsTools\Releases\\templates` for release version matching the one found in step 5. + 3. Replace the contents of the folder with the renamed package found in `..\bin\VS` + 5. 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 + 6. Delete the `%userprofile%\.templateengine` directory + +3. 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: +1. **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. + +2. **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. ```Javascript { @@ -80,7 +120,9 @@ The templates includes metadata files in addition to the files required to execu } ``` -- **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. +3. **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` + +4. **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. ```Javascript { @@ -107,65 +149,31 @@ The templates includes metadata files in addition to the files required to execu ] } ``` +5. **Sample.dat:** Sample.dat contains sample input data for each template. -# 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](Build/PackageFiles/Templates.nuspec) - -```XML - - - - -``` -3. Make sure the strings present in metadata.json are added to the [Resource file](Functions.Templates/Resources/Resources.resx). Strings are reference by adding '$' before the string name. For example `$TimerTriggerCSharp_description` present in the [metadata.json](Functions.Templates/Templates/TimerTrigger-CSharp/metadata.json) - +### 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. -# Adding dotnet templates -Dotnet used in Visual studio are driven by dotnet templating engine. Follow this [documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/custom-templates) to learn how to create dotnet templates. You can find more information on the templating engine at the [wiki page](https://github.com/dotnet/templating/wiki) of the dotnet templating repository. -- After you have created a dotnet template, Add the file entries to the ItemTemplates [nuspec file](Build/PackageFiles/ItemTemplates.nuspec). - -# Adding templates to extension bundle -1. Follow the steps mentioned in the [adding a new template](#adding-a-new-template) section. -2. Add the file entries to the [ExtensionBundleTemplates-1.x nuspec file](Build/PackageFiles/ExtensionBundleTemplates-1.x.nuspec) or [ExtensionBundleTemplates-2.x nuspec file](Build/PackageFiles/ExtensionBundleTemplates-2.x.nuspec) depending on your requirement. - -# Testing templates +|Nuspec File |Description| +|---|---| +|[ExtensionBundleTemplates-1.x.nuspec](Build\PackageFiles\ExtensionBundle\ExtensionBundleTemplates-1.x.nuspec) | Templates for Extension bundle v1 | +|[ExtensionBundleTemplates-2.x.nuspec](Build\PackageFiles\ExtensionBundle\ExtensionBundleTemplates-2.x.nuspec) | Templates for Extension bundle v2 | +|[ExtensionBundleTemplates-3.x.nuspec](Build\PackageFiles\ExtensionBundle\ExtensionBundleTemplates-3.x.nuspec) | Templates for Extension bundle v3 | +|[ExtensionBundlePreviewTemplates-3.x.nuspec](Build\PackageFiles\ExtensionBundle\ExtensionBundlePreviewTemplates-3.x.nuspec) | Templates for preview Extension bundle v3 | +|[ExtensionBundlePreviewTemplates-4.x.nuspec](Build\PackageFiles\ExtensionBundle\ExtensionBundlePreviewTemplates-4.x.nuspec) | Templates for preview Extension bundle v4 | -## Azure Function Core Tools +### Testing script type template via Core tools 1. Once the template files have been added / updated, build the templates using the [Build Steps](#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](#build-steps) -2. Make sure all instances of Visual Studio are closed -2. Open the `LastKnownGood` found at `%userprofile%\AppData\Local\AzureFunctionsTools\Tags\v2` -3. Note the release version present in the file -4. Open the templates folder `%userprofile%\AppData\Local\AzureFunctionsTools\Releases\\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.) -5. Replace the contents of the folder with the one found in `..\bin\VS` -6. Rename `Microsoft.Azure.WebJobs.ItemTemplates.X.0.0.nupkg` to `ItemTemplates.nupkg` -7. Delete the `%userprofile%\.templateengine` directory -8. 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](#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` +2. Locate the zip file for built template in the bin directory `..\bin\` +3. Extract the zip file content you want to test. This be based on the nuspec file you updated. +3. 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` +4. 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` +5. Replace the contents of the `StaticContent\v1` directory (path from step 4) with the files extracted from the zip file in step 3. +6. 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](http://www.dotnetfoundation.org/) and is licensed under [the MIT License](LICENSE.txt) This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. @@ -179,4 +187,4 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope ## 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](http://azure.github.com/guidelines.html). -If you encounter any bugs with the templates please file an issue in the [Issues](https://github.com/Azure/azure-webjobs-sdk-templates/issues) section of the project. +If you encounter any bugs with the templates please file an issue in the [Issues](https://github.com/Azure/azure-webjobs-sdk-templates/issues) section of the project. \ No newline at end of file