diff --git a/README.md b/README.md index 775754949..35501a67b 100644 --- a/README.md +++ b/README.md @@ -2,33 +2,47 @@ [![Version](https://vsmarketplacebadge.apphb.com/version/msazurermtools.azurerm-vscode-tools.svg)](https://marketplace.visualstudio.com/items?itemName=msazurermtools.azurerm-vscode-tools) [![Installs](https://vsmarketplacebadge.apphb.com/installs-short/msazurermtools.azurerm-vscode-tools.svg)](https://marketplace.visualstudio.com/items?itemName=msazurermtools.azurerm-vscode-tools) [![Build Status](https://dev.azure.com/ms-azuretools/AzCode/_apis/build/status/vscode-azurearmtools)](https://dev.azure.com/ms-azuretools/AzCode/_build/latest?definitionId=10) -The Azure Resource Manager (ARM) Tools for Visual Studio Code provides language support, resource snippets, and resource auto-completion to help you create and validate Azure Resource Manager templates. See the [Azure Resource Manager templates with Visual Studio Code quickstart](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/quickstart-create-templates-use-visual-studio-code?tabs=CLI) for a guided tutorial experience. +The Azure Resource Manager (ARM) Tools for Visual Studio Code provides language support, resource snippets, and resource auto-completion to help you create and validate Azure Resource Manager templates. -![ARM Tools creating web app](./images/arm-tools.gif) +## Getting Started -## Language Server +The following guides detail how to use the ARM Tools extension features. - - Azure Resource Manager template language server for providing ARM template language completion, validation, and error guidance. - - Resources are validated against Azure schemas, which provide validation based on resource type and apiVersion. - - ARM Template Outline view for easy navigation through large templates - - Colorization for Template Language Expressions (TLE) - - Analyze and validate JSON syntax, JSON schema conformance, and string expressions. +- [Snippets](#Snippets) +- [Azure schema integration](#Azure-schema-completion-and-validation) +- [Parameter file support](#parameter-files) +- [Completions](#completions) +- [Template navigation](#template-navigation) +- [Other features](#other-features) +- [Extension configuration](#extension-configuration) -## Parameter files +## Snippets -Template files can be mapped to a parameter file for an enhanced authoring and validation experience. To do so use the parameter file control in the Visual Studio Code status bar, or use the right-click contextual menu on an ARM template. Once a parameter file has been mapped, the following features are available. +Snippets are used to create basic templates and add elements such as parameters, resources, and outputs to existing templates. - - Full validation across both the template and parameter file - - Open an associated parameter file from a template - - Add all missing parameters to the parameter file and parameter auto-completion - - Rename parameters and all references across both the template and mapped parameter file - - Find and goto all references of a parameter across both the template and mapped parameter file +### Create a new ARM template -![Associate a parameters file with template and create parameters file](./images/params-support.gif) +When in an empty JSON file, typing `arm` produces a list of scaffolding snippets. These snippets can be used to create an empty template for any ARM deployment scope (Tenant, Subscription, Management Group, and Resource Group). -## Snippets +![Image showing the arm template scaffolding snippet](./images/json-snippets.png) + +Notice that adding scaffolding for an ARM template changes the Visual Studio Code language mode to *Azure Resource Manager Template*. + +![Image showing that the language type has changed to Azure Resource Manager Template](./images/arm-template-language.png) + +### Add Azure resource to an ARM template + +Once you are working in an ARM template, placing your cursor in the resource and typing `arm`, `CTRL + Space`, or `{` produces a list of 70+ snippets for Azure resources. Selecting a snippet adds an instance of the resource type to the ARM template. -Snippets for deployment template scaffolding and 70+ Azure resources. +![Image showing a storage account being added with a snippet](./images/arm-snippets.png) + +Each snippet includes tab stops to help navigate through commonly modified configurations. Press the `tab` key to navigate to the next stop, and `shift` + `tab` to navigate to the previous stop. As seen in the following example, some stops are pre-populated with a list of common values for quick selection. + +![Image showing snippet tab stops with pre-populated parameter values](./images/tab-stops.gif) + +### Snippet Reference + +The following table lists the available ARM Tools snippets. | Snippet | Description | |---|---| @@ -37,96 +51,189 @@ Snippets for deployment template scaffolding and 70+ Azure resources. | `arm!mg` | Adds the framework for a full deployment template file for management group deployments. | | `arm!t` | Adds the framework for a full deployment template file for tenant deployments. | | `armp!` | Adds the framework for a full deployment template parameters file. | -| `arm-param` | Adds a parameter to a template. | -| `arm-variable` | Adds a variable to a template. | -| `arm-userfunc` | Adds a user function to a template. | -| `arm-userfunc-namespace` | Adds a user function namespace to a template. | -| `arm-` | Displays 70+ snippets for creating Azure resources. For example, type `arm-ubuntu` to add all five resources necessary for a basic Ubuntu virtual machine. | +| `""` | While in the _parameters_ section adds a parameter to the template. | +| `""` | While in the _variables_ section adds a variable to the template. | +| `{}` | While in the _functions_ section add a new user-defined function. | +| `arm-` or the resource name | Displays 70+ snippets for creating Azure resources. For example, type `arm-ubuntu` to add all five resources necessary for a basic Ubuntu virtual machine. | +| `""` | While in the _outputs_ section adds an output to the template. | -## Insert Item +## Azure schema completion and validation -In addition to adding snippets from the code editor, the Insert Item feature can be used to insert new parameters, user-defined functions, variables, resources, and outputs. To do so right-click on the template in the code editor, select **Insert Item** and follow the on-screen prompts. +The ARM Tools extension uses Azure schemas to provide resource completion and validation. These schemas help you verify that Azure resources are configured correctly before deployment time. -![Inserting an item into an Azure Resource Manager template](./images/insert-item.png) +### Schema Completions -You can also right-click on any element in the ARM Template Outline view to initiate the insert item process. +Entering double quotes `""` or selecting `ctrl` + `space` while the cursor is in a resource declaration provides potential properties and property values for each Azure resource. -![Inserting an item into an Azure Resource Manager template](./images/insert-item-outline.png) +In the following example, the potential values for an Azure Storage account tier are returned from the Azure Storage schema. -## Intellisense +![Image showing a list of storage account tier values returned from the storage Azure schema](./images/completion.png) - - [Built-in functions](https://go.microsoft.com/fwlink/?LinkID=733958) - - [Parameter references](https://go.microsoft.com/fwlink/?LinkID=733959) - - [Variable references](https://go.microsoft.com/fwlink/?LinkID=733960) - - [resourceGroup() properties](https://azure.microsoft.com/en-us/documentation/articles/resource-group-template-functions/#resourcegroup) - - [subscription() properties](https://azure.microsoft.com/en-us/documentation/articles/resource-group-template-functions/#subscription) - - [resourceId() function](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-resource#resourceid) - - Properties of references to variables that are objects +### Schema Validation -## Other features +If an invalid property or property value is specified, a validation warning is shown. In the following example, an invalid value has been provided for the storage account tier (line 19). Notice that the warning message includes a list of valid values. - - [Signature help](https://code.visualstudio.com/docs/editor/editingevolved#_parameter-hints) for TLE function parameters - - [Go To Definition](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-definition) for variable and parameter references - - [Peek](https://code.visualstudio.com/docs/editor/editingevolved#_peek) for variable and parameter definitions - - Find all references (Shift + F12) for variables and parameters - - Rename (F2) variables and parameters and their references - - [Hover](https://code.visualstudio.com/docs/editor/editingevolved#_hover) for parameter description - - [TLE brace matching](https://code.visualstudio.com/docs/editor/editingevolved#_bracket-matching) - - User-defined template functions, see Azure [documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-authoring-templates#functions) - - Variable iteration ("copy blocks"), see Azure [documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-multiple#variable-iteration) - - Sort template and template sections alphabetically +![Image showing a schema validation error](./images/schema-validation.png) -## Extension configurations +## Parameter files -You may be interested in adjusting the following extension configurations. These can be configured in [VS Code User Settings](https://code.visualstudio.com/docs/getstarted/settings). +Associating a parameter file with an ARM template enables full validation across both the parameter file and template. A parameter file association can be made by either creating a new parameter file from an existing template or by associating an existing parameter file to the template. -**Auto-detect ARM Templates** +### Create a new parameter file -Enables auto-detection of deployment template files with the extension *.json or *.jsonc. If set to true (default), the editor language will automatically be set to Azure Resource Manager Template for any *.json/*.jsonc file which contains an appropriate Azure Resource Manager Template schema. +To create a new parameter file from an existing template, click on the code lens text `**Select or create a parameter file to enable full validation..**. -``` -"azureResourceManagerTools.autoDetectJsonTemplates": true, -``` +![Image showing the code lens for creating a parameter file association](./images/create-parameter-file.png) -**Detect latest root schema** +Select **New** from the context menu. -Check if the root schema for deployment templates is using an out-of-date version and suggest updating it to the latest version. +![Image showing the parameter file creation options (none, new, and browse)](./images/create-parameter-file-2.png) -``` -"azureResourceManagerTools.checkForLatestSchema": true, -``` +Selecting **All parameters** adds every parameter from the template into the new parameter file. Selecting **Only required parameters** adds only parameters that do not have a default value specified in the template file. -**Parameter files** +![Image showing options for adding parameters for parameter file (All parameters, only required parameters)](./images/create-parameter-file-3.png) -Check if an opened template file has a matching params file and prompt to create a mapping. +Select a name and location for the parameter file. -``` -"azureResourceManagerTools.checkForMatchingParameterFiles": true, -``` +![Image showing a file save as dialog box](./images/create-parameter-file-4.png) -Parameter file mappings are stored in the `azureResourceManagerTools.parameterFiles` user setting. +Once done, a parameter file has been created. Where needed, remove the _TODO_ comment and add a parameter value. -``` -"azureResourceManagerTools.parameterFiles": {} -``` +![Image showing new parameter file](./images/parameter-file.png) -**Code Lens** +Also, notice that on the template file that the code lens text has been updated to reflect the current parameter file association. This association is also shown on the Visual Studio Code staus bar. -Disable all code lens functionality -``` -"azureResourceManagerTools.codelens.enable": false -``` +![Image showing that the parameter code lens has been updated to reflect associated parameter file](./images/code-lens.png) -Disable code lens for parameters -``` -"azureResourceManagerTools.codelens.parameters": false -``` +### Associate an existing parameter file + +To create an association with an existing parameter file, click on the code lens text `**Select or create a parameter file to enable full validation**'. + +![Image showing the code lens for creating a parameter file association](./images/create-parameter-file.png) + +If a parameter file with a matching name (template name + "_.parameter_") is found, it can be selected from the list. If a matching file is not found, select **Browse** from the list and then select the parameter file. + +![Image showing the parameter file creation options (none, new, and browse)](./images/create-parameter-file-2.png) + +### Parameter validation + +Once a parameter file has been associated with a template, the extension provides parameter validation across both files. In the following example, a parameter is specified with a set of allowed values. In the parameter file, a value is specified that is not part of the allowed values list. Because of this, the extension produces an error. + +![Image showing a parameter validation issue](./images/param-file-validation.png) + +### Add missing parameters + +To add missing parameters to an existing parameter file, ensure that an association has been created, click somewhere inside "_parameters_", and then click the light bulb icon. + +![Image showing the light bulb helper for adding missing parameters](./images/missing-params-one.png) + +Select the option to add only required or all missing parameters. + +![Image showing missing parameter options (Add missing required parameters, Add all missing parameters)](./images/missing-params-two.png) + +Enter a value for the added parameters and also remove the 'TODO' comment. + +![Image showing parameter file after missing parameters have been added](./images/missing-params-three.png) + +### Rename a parameter + +Right-click on the parameter name and select **Rename Symbol**. This action renames the parameter and all template and parameter file references to the parameter. + +![Image showing the rename parameter dialoug](./images/rename-parameter.png) + +### Remove or update parameter file association + +Click on the code lens option for changing a parameter association. + +![Image showing the code lens for creating a parameter file association](./images/undo-change-mapping.png) + +Select a new parameter file or create a new parameter file to update the association. Select **None** to remove the parameter file association. + +![Image showing the parameter file creation options (none, new, and browse)](./images/undo-change-mapping-two.png) + +## Template navigation + +The ARM tools extension for VS Code offers several features for navigating around an ARM template. + +### ARM template outline + +The ARM template outline is used to navigate to and select any element of an ARM template. + +![Image showing the ARM template outline with a storage account resource selected](./images/arm-template-outline.png) + +In addition to navigation, several features such as insert item and template sorting can be engaged using the buttons found on the ARM template outline. + +### Go to Definition + +Go to definition can be used to navigate to parameter, variable and user-defined function definitions. To use go to definition, place your cursor on the parameter, variable or function name and press `F12` or right-click and select **Go to Definition**. + +![Image showing the Go to Definition dialog on a parameter reference](./images/go-to-definition.png) + +### Find all references + +Right-click on a parameter, variable, or user-defined function name and select **Go to References**. Double-clicking on any reference moves your cursor to the reference location. + +![Image showing the go to reference user interface](./images/parameter-references.png) + +## Completions + +The ARM Tools extension provides code completions for many [built-in functions](https://go.microsoft.com/fwlink/?LinkID=733958) such as resourceId and variable. + +## Other features + +### Insert Item + +In addition to adding snippets from the code editor, the Insert Item feature can be used to insert new parameters, user-defined functions, variables, resources, and outputs. To do so right-click the code editor, select **Insert Item** and follow the on-screen prompts. + +![Inserting an item into an Azure Resource Manager template](./images/insert-item.png) + +You can also right-click on any element in the ARM Template Outline view to initiate the insert item process. + +![Inserting an item into an Azure Resource Manager template](./images/insert-item-outline.png) + +### Sort template + +To sort elements of an ARM template alphabetically, right-click on the template and select **Sort Template...**. + +![Image showing the sort template options (Resource, Function, Output, Parameter, Variable)](./images/sort-template.png) + +Select the element that you want to sort. + +![Image showing the insert resource menu](./images/sort-template-two.png) + +Template sorting can also be engaged using the ARM template outline. + +### Miscellaneous Features + + - [Signature help](https://code.visualstudio.com/docs/editor/editingevolved#_parameter-hints) for TLE function parameters + - [Peek](https://code.visualstudio.com/docs/editor/editingevolved#_peek) for variable and parameter definitions + - Find all references (Shift + F12) for variables and parameters + - Rename (F2) variables and parameters and their references, as well as user-defined functions or namespaces + - [Hover](https://code.visualstudio.com/docs/editor/editingevolved#_hover) for parameter description + - [TLE brace matching](https://code.visualstudio.com/docs/editor/editingevolved#_bracket-matching) + - User-defined template functions, see Azure [documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-authoring-templates#functions) + - Variable iteration ("copy blocks"), see Azure [documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-multiple#variable-iteration) + - Sort template and template sections alphabetically + - Nested templates (with inner or outer scope) + - Quick fix to add missing parameter values in the parameter file or in nested templates + +## Extension configuration + +You may be interested in adjusting the following extension configurations. These can be configured in [VS Code User Settings](https://code.visualstudio.com/docs/getstarted/settings). + +| Configuration | Description | +|---|---| +| azureResourceManagerTools.autoDetectJsonTemplates | Auto-detects ARM template and sets editor language type to Azure Resource Manager Template. | +| azureResourceManagerTools.checkForLatestSchema | Check if the root schema for deployment templates is using an out-of-date version and suggest updating it to the latest version. | +| azureResourceManagerTools.checkForMatchingParameterFiles | Check if an opened template file has a matching parameter file and prompt to create an association. | +| azureResourceManagerTools.codelens.enable | Set to false to disable all code lens functionality. | +| azureResourceManagerTools.codelens.parameters | Set to false to disable code lens for parameters. | ## Automatic Detection of deployment template files By default, the extension recognizes a .json or .jsonc file as a deployment template file based on the \$schema specified in the file (for instance, `https://schema.management.azure.com/schemas/2018-05-01/deploymentTemplate.json#`) and will switch the editor language to "Azure Resource Manager Template" automatically. If you do not want that behavior, you can set the `azureResourceManagerTools.autoDetectJsonTemplates` setting to false and use the below methods to determine which files to treat as deployment templates. -Besides automatic detection, you can also use the `files.associations` setting to set up your own specific mappings based on specific files paths or patterns to mark them as deployment templates, e.g. +Besides automatic detection, you can also use the `files.associations` setting to set up your own specific associations based on specific files paths or patterns to mark them as deployment templates, e.g. ```json "files.associations": { @@ -138,8 +245,8 @@ Besides automatic detection, you can also use the `files.associations` setting t Use the following wiki article to help troubleshoot these known issues. -- [Could not find/download: ".NET Core Runtime" with version = 2.2.5](https://github.com/microsoft/vscode-azurearmtools/wiki/Troubleshooting-DotNet-Acquisition) -- [Unrecognized Resource API Version](https://github.com/microsoft/vscode-azurearmtools/wiki/Unrecognized-Resource-API-Version) +- [This extension requires .NET Core for full functionality, but we were unable to download and install a local copy for the extension.](https://github.com/microsoft/vscode-azurearmtools/wiki/Troubleshooting-DotNet-Acquisition) +- [Resource schema warning: "For full schema validation, consider updating the value to one of the following..."](https://github.com/microsoft/vscode-azurearmtools/wiki/Unrecognized-Resource-API-Version) ## Related Links diff --git a/images/arm-snippets.png b/images/arm-snippets.png new file mode 100644 index 000000000..42091378a Binary files /dev/null and b/images/arm-snippets.png differ diff --git a/images/arm-template-language.png b/images/arm-template-language.png new file mode 100644 index 000000000..11e5173ab Binary files /dev/null and b/images/arm-template-language.png differ diff --git a/images/arm-template-outline.png b/images/arm-template-outline.png new file mode 100644 index 000000000..837dca6da Binary files /dev/null and b/images/arm-template-outline.png differ diff --git a/images/arm-tools.gif b/images/arm-tools.gif deleted file mode 100644 index 962558e05..000000000 Binary files a/images/arm-tools.gif and /dev/null differ diff --git a/images/code-lens.png b/images/code-lens.png new file mode 100644 index 000000000..249599ad4 Binary files /dev/null and b/images/code-lens.png differ diff --git a/images/completion.png b/images/completion.png new file mode 100644 index 000000000..e1ec918a4 Binary files /dev/null and b/images/completion.png differ diff --git a/images/create-parameter-file-2.png b/images/create-parameter-file-2.png new file mode 100644 index 000000000..2d69422d5 Binary files /dev/null and b/images/create-parameter-file-2.png differ diff --git a/images/create-parameter-file-3.png b/images/create-parameter-file-3.png new file mode 100644 index 000000000..d9736ff17 Binary files /dev/null and b/images/create-parameter-file-3.png differ diff --git a/images/create-parameter-file-4.png b/images/create-parameter-file-4.png new file mode 100644 index 000000000..899e3d118 Binary files /dev/null and b/images/create-parameter-file-4.png differ diff --git a/images/create-parameter-file.png b/images/create-parameter-file.png new file mode 100644 index 000000000..c04a64ff8 Binary files /dev/null and b/images/create-parameter-file.png differ diff --git a/images/go-to-definition.png b/images/go-to-definition.png new file mode 100644 index 000000000..d775f2fff Binary files /dev/null and b/images/go-to-definition.png differ diff --git a/images/insert-item-outline.png b/images/insert-item-outline.png index ef4bfdd99..5890f6513 100644 Binary files a/images/insert-item-outline.png and b/images/insert-item-outline.png differ diff --git a/images/insert-item.png b/images/insert-item.png index 1a03ce3c4..00e5a433a 100644 Binary files a/images/insert-item.png and b/images/insert-item.png differ diff --git a/images/json-snippets.png b/images/json-snippets.png new file mode 100644 index 000000000..c7bb9723c Binary files /dev/null and b/images/json-snippets.png differ diff --git a/images/missing-params-one.png b/images/missing-params-one.png new file mode 100644 index 000000000..b17007d45 Binary files /dev/null and b/images/missing-params-one.png differ diff --git a/images/missing-params-three.png b/images/missing-params-three.png new file mode 100644 index 000000000..bde5b5acd Binary files /dev/null and b/images/missing-params-three.png differ diff --git a/images/missing-params-two.png b/images/missing-params-two.png new file mode 100644 index 000000000..ba1244d2c Binary files /dev/null and b/images/missing-params-two.png differ diff --git a/images/param-file-validation.png b/images/param-file-validation.png new file mode 100644 index 000000000..28ff671cd Binary files /dev/null and b/images/param-file-validation.png differ diff --git a/images/parameter-file.png b/images/parameter-file.png new file mode 100644 index 000000000..65346c42f Binary files /dev/null and b/images/parameter-file.png differ diff --git a/images/parameter-references.png b/images/parameter-references.png new file mode 100644 index 000000000..8498f6d5b Binary files /dev/null and b/images/parameter-references.png differ diff --git a/images/params-support.gif b/images/params-support.gif deleted file mode 100644 index ae491778c..000000000 Binary files a/images/params-support.gif and /dev/null differ diff --git a/images/rename-parameter.png b/images/rename-parameter.png new file mode 100644 index 000000000..c6aba5e11 Binary files /dev/null and b/images/rename-parameter.png differ diff --git a/images/schema-validation.png b/images/schema-validation.png new file mode 100644 index 000000000..d49903c25 Binary files /dev/null and b/images/schema-validation.png differ diff --git a/images/sort-template-two.png b/images/sort-template-two.png new file mode 100644 index 000000000..96da5f4d0 Binary files /dev/null and b/images/sort-template-two.png differ diff --git a/images/sort-template.png b/images/sort-template.png new file mode 100644 index 000000000..2c61b82aa Binary files /dev/null and b/images/sort-template.png differ diff --git a/images/tab-stops.gif b/images/tab-stops.gif new file mode 100644 index 000000000..88c29103a Binary files /dev/null and b/images/tab-stops.gif differ diff --git a/images/undo-change-mapping-two.png b/images/undo-change-mapping-two.png new file mode 100644 index 000000000..ad410bbf5 Binary files /dev/null and b/images/undo-change-mapping-two.png differ diff --git a/images/undo-change-mapping.png b/images/undo-change-mapping.png new file mode 100644 index 000000000..2dfbb57d5 Binary files /dev/null and b/images/undo-change-mapping.png differ diff --git a/images/validation.png b/images/validation.png new file mode 100644 index 000000000..5938f3587 Binary files /dev/null and b/images/validation.png differ