Update templates and JsonCLI docs (#2975)
This commit is contained in:
Eric Jizba
GitHub
Родитель
63f07d1312
Коммит
3873f9b99d
|
|
@ -69,7 +69,7 @@ dist
|
|||
stats.json
|
||||
|
||||
# debugging artifacts
|
||||
resources/dotnetTemplates
|
||||
resources/backupTemplates/dotnet/**/cache/
|
||||
|
||||
# macOS related extra files
|
||||
.DS_Store
|
||||
|
|
|
|||
|
|
@ -1,15 +1,37 @@
|
|||
# Azure Function Templates
|
||||
|
||||
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:
|
||||
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.
|
||||
|
||||
* [Script Templates](#script-templates) (i.e. JavaScript, C#Script, and Python)
|
||||
* [.NET Templates](#.net-templates) (i.e. C#)
|
||||
## Template Sources
|
||||
|
||||
Templates are retrieved from the following sources, in order:
|
||||
1. VS Code extension cache, if the cached version matches the latest version from the CLI Feed
|
||||
1. Latest templates from the CLI Feed
|
||||
1. VS Code extension cache, if we fail to get the latest templates or it times out
|
||||
1. Backup templates stored in `resources/backupTemplates`, if we fail to get the latest templates and the cache is empty
|
||||
|
||||
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.
|
||||
|
||||
### Updating Backup Templates
|
||||
|
||||
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:
|
||||
1. Modify `AZFUNC_UPDATE_BACKUP_TEMPLATES` to `1` in `.vscode/launch.json`
|
||||
1. Select "Launch Tests" as the debug configuration
|
||||
1. F5 the extension
|
||||
1. Commit changes
|
||||
|
||||
> 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.
|
||||
|
||||
## Script Templates
|
||||
|
||||
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:
|
||||
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
|
||||
|
||||
### Templates.json
|
||||
> 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".
|
||||
|
||||
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:
|
||||
|
||||
<details>
|
||||
<summary>templates.json</summary>
|
||||
|
||||
```json
|
||||
[
|
||||
|
|
@ -50,7 +72,10 @@ Script templates are retrieved from the 'templateApiZip' property in the CLI Fee
|
|||
]
|
||||
```
|
||||
|
||||
### BindingConfig.json
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>bindings.json</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -101,7 +126,10 @@ Script templates are retrieved from the 'templateApiZip' property in the CLI Fee
|
|||
}
|
||||
```
|
||||
|
||||
### Resources.json
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>resources.json</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -121,46 +149,8 @@ Script templates are retrieved from the 'templateApiZip' property in the CLI Fee
|
|||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## .NET Templates
|
||||
|
||||
.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.
|
||||
|
||||
The following is an example command used to list templates:
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
Example format for the Timer Trigger:
|
||||
|
||||
```json
|
||||
{
|
||||
"Author": "Microsoft",
|
||||
"Classifications": [
|
||||
"Azure Function"
|
||||
],
|
||||
"DefaultName": "TimerTriggerCSharp",
|
||||
"Identity": "Azure.Function.CSharp.TimerTrigger.1.x",
|
||||
"GroupIdentity": "Azure.Function.TimerTrigger",
|
||||
"Name": "TimerTrigger",
|
||||
"ShortName": "Timer",
|
||||
"Parameters": [
|
||||
{
|
||||
"Documentation": "Enter a cron expression of the format '{second} {minute} {hour} {day} {month} {day of week}' to specify the schedule.",
|
||||
"Name": "Schedule",
|
||||
"Priority": 0,
|
||||
"Type": null,
|
||||
"IsName": false,
|
||||
"DefaultValue": "0 */5 * * * *",
|
||||
"DataType": null,
|
||||
"Choices": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
And the following is an example command for creating a template:
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
.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.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,23 @@
|
|||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": ".NET Core Launch (list templates)",
|
||||
"type": "coreclr",
|
||||
"request": "launch",
|
||||
"preLaunchTask": "build",
|
||||
"program": "${workspaceFolder}/src/bin/Debug/netcoreapp3.0/Microsoft.TemplateEngine.JsonCli.dll",
|
||||
"args": [
|
||||
"--templateDir",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/netcoreapp3.1/",
|
||||
"--operation",
|
||||
"list"
|
||||
],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"console": "internalConsole",
|
||||
"stopAtEntry": false,
|
||||
"internalConsoleOptions": "openOnSessionStart"
|
||||
},
|
||||
{
|
||||
"name": ".NET Core Launch (create function)",
|
||||
"type": "coreclr",
|
||||
|
|
@ -8,10 +25,8 @@
|
|||
"preLaunchTask": "build",
|
||||
"program": "${workspaceFolder}/src/bin/Debug/netcoreapp3.0/Microsoft.TemplateEngine.JsonCli.dll",
|
||||
"args": [
|
||||
"--require",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/projectTemplates-~3.nupkg",
|
||||
"--require",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/itemTemplates-~3.nupkg",
|
||||
"--templateDir",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/netcoreapp3.1/",
|
||||
"--operation",
|
||||
"create",
|
||||
"--identity",
|
||||
|
|
@ -32,10 +47,8 @@
|
|||
"preLaunchTask": "build",
|
||||
"program": "${workspaceFolder}/src/bin/Debug/netcoreapp3.0/Microsoft.TemplateEngine.JsonCli.dll",
|
||||
"args": [
|
||||
"--require",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/projectTemplates-~3.nupkg",
|
||||
"--require",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/itemTemplates-~3.nupkg",
|
||||
"--templateDir",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/netcoreapp3.1/",
|
||||
"--operation",
|
||||
"create",
|
||||
"--identity",
|
||||
|
|
@ -49,25 +62,6 @@
|
|||
"console": "internalConsole",
|
||||
"stopAtEntry": false,
|
||||
"internalConsoleOptions": "openOnSessionStart"
|
||||
},
|
||||
{
|
||||
"name": ".NET Core Launch (list templates)",
|
||||
"type": "coreclr",
|
||||
"request": "launch",
|
||||
"preLaunchTask": "build",
|
||||
"program": "${workspaceFolder}/src/bin/Debug/netcoreapp3.0/Microsoft.TemplateEngine.JsonCli.dll",
|
||||
"args": [
|
||||
"--require",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/projectTemplates-~3.nupkg",
|
||||
"--require",
|
||||
"${workspaceFolder}/../../resources/backupTemplates/dotnet/~3/itemTemplates-~3.nupkg",
|
||||
"--operation",
|
||||
"list"
|
||||
],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"console": "internalConsole",
|
||||
"stopAtEntry": false,
|
||||
"internalConsoleOptions": "openOnSessionStart"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4,19 +4,21 @@
|
|||
|
||||
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.
|
||||
|
||||
> 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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
[.NET CLI](https://docs.microsoft.com/dotnet/core/tools/?tabs=netcore2x)
|
||||
[.NET CLI](https://docs.microsoft.com/dotnet/core/tools/)
|
||||
|
||||
## Example Usage
|
||||
|
||||
### List
|
||||
|
||||
```bash
|
||||
dotnet --require ./projectTemplates-~2.nupkg --require ./itemTemplates-~2.nupkg --operation list
|
||||
dotnet --templateDir ./../../resources/backupTemplates/dotnet/~3/netcoreapp3.1/ --operation list
|
||||
```
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```json
|
||||
[
|
||||
|
|
@ -49,10 +51,10 @@ This will list all templates included in the NuGet packages specified with the `
|
|||
### Create
|
||||
|
||||
```bash
|
||||
dotnet --require projectTemplates-~2.nupkg --require itemTemplates-~2.nupkg --operation create --identity Azure.Function.CSharp.TimerTrigger.1.x --arg:name TimerTriggerCSharp1 --arg:namespace Company.Function --arg:Schedule "0 */5 * * * *"
|
||||
dotnet --templateDir ./../../resources/backupTemplates/dotnet/~3/netcoreapp3.1/ --operation create --identity Azure.Function.CSharp.TimerTrigger.1.x --arg:name TimerTriggerCSharp1 --arg:namespace Company.Function --arg:Schedule "0 */5 * * * *"
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -61,14 +63,9 @@ In order to work on this tool, make sure to install the [VS Code Debugger for C#
|
|||
### Debug
|
||||
|
||||
1. When prompted, make sure to restore NuGet packages
|
||||
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/`.
|
||||
1. From the debug window, select either the 'create template' or 'list templates' option based on what you want to test
|
||||
1. From the debug window, select either the 'create function', 'create project', or 'list templates' option based on what you want to test
|
||||
1. Start debugging!
|
||||
|
||||
### Publish
|
||||
|
||||
In order to update the dll's shipped with the extension, you need to run a 'publish':
|
||||
|
||||
1. Select 'Run Task' from the command palette
|
||||
1. Select 'publish'
|
||||
1. Commit changes
|
||||
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.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче