You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/templates/README.md
+38-48
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,37 @@
1
1
# Azure Function Templates
2
2
3
-
The code in this folder is used to parse and model the [function templates](https://github.com/Azure/azure-webjobs-sdk-templates) provided by the [Azure Functions CLI Feed](https://aka.ms/V00v5v). The Functions CLI Feed provides a central location to get the latest version of all templates used for functions. Currently, this repo leverages the following templates:
3
+
The code in this folder is used to parse and model the [function templates](https://github.com/Azure/azure-webjobs-sdk-templates) provided by the [Azure Functions CLI Feed](https://aka.ms/AAbbk68). The Functions CLI Feed provides a central location to get the latest version of all templates used for functions.
4
4
5
-
*[Script Templates](#script-templates) (i.e. JavaScript, C#Script, and Python)
6
-
*[.NET Templates](#.net-templates) (i.e. C#)
5
+
## Template Sources
6
+
7
+
Templates are retrieved from the following sources, in order:
8
+
1. VS Code extension cache, if the cached version matches the latest version from the CLI Feed
9
+
1. Latest templates from the CLI Feed
10
+
1. VS Code extension cache, if we fail to get the latest templates or it times out
11
+
1. Backup templates stored in `resources/backupTemplates`, if we fail to get the latest templates and the cache is empty
12
+
13
+
Unit test run separately against all of these template sources (cache, latest, backup) in addition to "staging", which is the pre-production version of "latest". Different template sources can be tested manually with the "azureFunctions.templateSource" setting.
14
+
15
+
### Updating Backup Templates
16
+
17
+
Backup templates should be updated every time there is a major change in the latest templates, and otherwise periodically with the release of the extension. In order to update:
18
+
1. Modify `AZFUNC_UPDATE_BACKUP_TEMPLATES` to `1` in `.vscode/launch.json`
19
+
1. Select "Launch Tests" as the debug configuration
20
+
1. F5 the extension
21
+
1. Commit changes
22
+
23
+
> NOTE: This tool was written as a "test" so that it can run in the context of VS Code and our extension. This allows the "backup template" code to be much more tightly integrated with the core templates code, as opposed to something like a gulp task which would have to be completely separate.
7
24
8
25
## Script Templates
9
26
10
-
Script templates are retrieved from the 'templateApiZip' property in the CLI Feed. The zip contains data in three parts: templates.json, bindingconfig.json, and resources.json. See below for an example of the schema for the TimerTrigger template:
27
+
Basic script templates (i.e. http and timer) are retrieved from the 'templates' property in each entry of the [CLI Feed](https://aka.ms/AAbbk68). More advanced templates (i.e. blob and cosmos) are retrieved from another feed specific to the extension bundle for that project. For example, the default bundle is 'Microsoft.Azure.Functions.ExtensionBundle' and the matching feed is https://functionscdn.azureedge.net/public/ExtensionBundles/Microsoft.Azure.Functions.ExtensionBundle/index-v2.json
28
+
29
+
> NOTE: Both template feeds support 'staging' environments for us to test against before moving to production. The main CLI Feed uses a "vX-prerelease" tag, while the bundle feed has a completely different url leveraging "functionscdnstaging" instead of "functionscdn".
30
+
31
+
In both cases, the templates are split into three parts: templates.json, bindings.json, and resources.json. See below for an example of the schema for the TimerTrigger template:
11
32
12
-
### Templates.json
33
+
<details>
34
+
<summary>templates.json</summary>
13
35
14
36
```json
15
37
[
@@ -50,7 +72,10 @@ Script templates are retrieved from the 'templateApiZip' property in the CLI Fee
50
72
]
51
73
```
52
74
53
-
### BindingConfig.json
75
+
</details>
76
+
77
+
<details>
78
+
<summary>bindings.json</summary>
54
79
55
80
```json
56
81
{
@@ -101,7 +126,10 @@ Script templates are retrieved from the 'templateApiZip' property in the CLI Fee
101
126
}
102
127
```
103
128
104
-
### Resources.json
129
+
</details>
130
+
131
+
<details>
132
+
<summary>resources.json</summary>
105
133
106
134
```json
107
135
{
@@ -121,46 +149,8 @@ Script templates are retrieved from the 'templateApiZip' property in the CLI Fee
121
149
}
122
150
```
123
151
124
-
## .NET Templates
125
-
126
-
.NET templates are retrieved from the 'itemTemplates' and 'projectTemplates' properties in the CLI Feed. These properties reference two nuget packages. We then leverage the 'Microsoft.TemplateEngine.JsonCli' dll which provides a JSON-based way to interact with .NET templates.
152
+
</details>
127
153
128
-
The following is an example command used to list templates:
129
-
130
-
```
131
-
dotnet <path to extension>/resources/dotnetJsonCli/Microsoft.TemplateEngine.JsonCli.dll --require <path to extension>/resources/dotnetTemplates/itemTemplates-~1.nupkg --require <path to extension>/resources/dotnetTemplates/projectTemplates-~1.nupkg --operation list
"Documentation": "Enter a cron expression of the format '{second} {minute} {hour} {day} {month} {day of week}' to specify the schedule.",
150
-
"Name": "Schedule",
151
-
"Priority": 0,
152
-
"Type": null,
153
-
"IsName": false,
154
-
"DefaultValue": "0 */5 * * * *",
155
-
"DataType": null,
156
-
"Choices": null
157
-
}
158
-
]
159
-
}
160
-
```
161
-
162
-
And the following is an example command for creating a template:
154
+
## .NET Templates
163
155
164
-
```
165
-
dotnet <path to extension>/resources/dotnetJsonCli/Microsoft.TemplateEngine.JsonCli.dll --require <path to extension>/resources/dotnetTemplates/itemTemplates-~2.nupkg --require <path to extension>/resources/dotnetTemplates/projectTemplates-~2.nupkg --operation create --identity Azure.Function.CSharp.TimerTrigger.2.x --arg:Schedule 0 */5 * * * * --arg:name TimerTriggerCSharp --arg:namespace Company.Function
166
-
```
156
+
.NET templates are retrieved from the 'itemTemplates' and 'projectTemplates' properties in the CLI Feed. A single version of the Azure Functions runtime might support multiple versions of the .NET runtime, so we use the target framework and sdk from a user's `*.csproj` file to pick the matching templates. We then leverage the JsonCLI tool ('Microsoft.TemplateEngine.JsonCli') which provides a JSON-based way to interact with .NET templates. More information on that tool can be found in the [tools/JsonCli](https://github.com/microsoft/vscode-azurefunctions/tree/main/tools/JsonCli) folder at the root of this repo.
Copy file name to clipboardExpand all lines: tools/JsonCli/README.md
+9-12
Original file line number
Diff line number
Diff line change
@@ -4,19 +4,21 @@
4
4
5
5
This tool is leveraged by the Functions extension at the root of this repo. It provides a JSON-based way to interact with .NET Templates. It also allows us to use templates directly from a nuget package, rather than forcing the user to install the templates machine-wide.
6
6
7
+
> NOTE: This tool assumes the user already has the .NET CLI installed on their machine, but that means we have to ship multiple target frameworks with the extension to work with whatever they have installed. One alternative would be to leverage the [.NET Install Tool](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.vscode-dotnet-runtime) to install a specific version of .NET and then the extension would only need to ship that target framework.
dotnet --require ./projectTemplates-~2.nupkg --require ./itemTemplates-~2.nupkg --operation list
18
+
dotnet --templateDir ./../../resources/backupTemplates/dotnet/~3/netcoreapp3.1/ --operation list
17
19
```
18
20
19
-
This will list all templates included in the NuGet packages specified with the `require` parameter. Multiple packages can be specified in the format of a disk path, a NuGet package ID, or a NuGet package ID and version formatted as `{id}::{version}`. Example output:
21
+
This will list all templates based on the `templateDir` parameter. The template directory should have an "item.nupkg" for item templates and a "project.nupkg" for project templates. Example output:
20
22
21
23
```json
22
24
[
@@ -49,10 +51,10 @@ This will list all templates included in the NuGet packages specified with the `
This will create the template with the specified identity. The `require` parameter is the same as used above. The `identity` and `arg` parameters can be retrieved from the result of a list operation, shown above. The `name` and `namespace` args apply to all templates.
57
+
This will create the template with the specified identity. The `templateDir` parameter is the same as used above. The `identity` and `arg` parameters can be retrieved from the result of a list operation, shown above. The `name` and `namespace` args apply to all templates.
56
58
57
59
## Contributing
58
60
@@ -61,14 +63,9 @@ In order to work on this tool, make sure to install the [VS Code Debugger for C#
61
63
### Debug
62
64
63
65
1. When prompted, make sure to restore NuGet packages
64
-
1. Ensure the latest .NET templates are downloaded. The easiest way is to F5 the extension at the root of this repo and open the Functions explorer to make sure the extension is activated. This will automatically download the latest NuGet packages to `resources/dotnetTemplates/`.
65
-
1. From the debug window, select either the 'create template' or 'list templates' option based on what you want to test
66
+
1. From the debug window, select either the 'create function', 'create project', or 'list templates' option based on what you want to test
66
67
1. Start debugging!
67
68
68
69
### Publish
69
70
70
-
In order to update the dll's shipped with the extension, you need to run a 'publish':
71
-
72
-
1. Select 'Run Task' from the command palette
73
-
1. Select 'publish'
74
-
1. Commit changes
71
+
In order to update the dll's shipped with the extension, you need to [run a build](https://devdiv.visualstudio.com/DefaultCollection/DevDiv/_build?definitionId=13600) with `SignType` set to `Real` and download those bits into the `resources/dotnetJsonCli` folder as appropriate.
0 commit comments