Merge pull request #206531 from edburns/edburns-msft-96155-jsonc-mention

Increase discoverability of jsonc feature in ARM

Author: PRMerger9

articles/azure-resource-manager/templates/best-practices.md

@@ -189,6 +189,23 @@ The following information can be helpful when you work with [resources](./syntax
     ]
     ```
 
+   If your ARM template is stored in a `.jsonc` file, comments using the `//` syntax are supported, as shown here.
+
+    ```javascript
+    "resources": [
+      {
+        // This storage account is used to store the VM disks.
+        "name": "[variables('storageAccountName')]",
+        "type": "Microsoft.Storage/storageAccounts",
+        "apiVersion": "2019-06-01",
+        "location": "[resourceGroup().location]",
+          ...
+      }
+    ]
+    ```
+
+   For more details about comments and metadata see [Understand the structure and syntax of ARM templates](/azure/azure-resource-manager/templates/syntax#comments-and-metadata).
+
 * If you use a *public endpoint* in your template (such as an Azure Blob storage public endpoint), *don't hard-code* the namespace. Use the `reference` function to dynamically retrieve the namespace. You can use this approach to deploy the template to different public namespace environments without manually changing the endpoint in the template. Set the API version to the same version that you're using for the storage account in your template.
 
     ```json
@@ -272,6 +289,14 @@ The following information can be helpful when you work with [resources](./syntax
 
 * Specify explicit values for properties that have default values that could change over time. For example, if you're deploying an AKS cluster, you can either specify or omit the `kubernetesVersion` property. If you don't specify it, then [the cluster is defaulted to the N-1 minor version and latest patch](../../aks/supported-kubernetes-versions.md#azure-portal-and-cli-versions). When you deploy the cluster using an ARM template, this default behavior might not be what you expect. Redeploying your template may result in the cluster being upgraded to a new Kubernetes version unexpectedly. Instead, consider specifying an explicit version number and then manually changing it when you're ready to upgrade your cluster.
 
+## Comments
+
+In addition to the `comments` property, comments using the `//` syntax are supported.  For more details about comments and metadata see [Understand the structure and syntax of ARM templates](/azure/azure-resource-manager/templates/syntax#comments-and-metadata). You may choose to save JSON files that contain `//` comments using the `.jsonc` file extension, to indicate the JSON file contains comments. The ARM service will also accept comments in any JSON file including parameters files.
+
+## Visual Studio Code ARM Tools
+
+Working with ARM templates is much easier with the Azure Resource Manager (ARM) Tools for Visual Studio Code. This extension provides language support, resource snippets, and resource auto-completion to help you create and validate Azure Resource Manager templates. To learn more and install the extension, see [Azure Resource Manager (ARM) Tools](https://marketplace.visualstudio.com/items?itemName=msazurermtools.azurerm-vscode-tools).
+
 ## Use test toolkit
 
 The ARM template test toolkit is a script that checks whether your template uses recommended practices. When your template isn't compliant with recommended practices, it returns a list of warnings with suggested changes. The test toolkit can help you learn how to implement best practices in your template.

articles/azure-resource-manager/templates/deploy-cli.md

@@ -79,6 +79,8 @@ az deployment group create \
   --parameters storageAccountType=Standard_GRS
 ```
 
+The value of the `--template-file` parameter must be a Bicep file or a `.json` or `.jsonc` file. The `.jsonc` file extension indicates the file can contain `//` style comments. The ARM system accepts `//` comments in `.json` files. It does not care about the file extension. For more details about comments and metadata see [Understand the structure and syntax of ARM templates](/azure/azure-resource-manager/templates/syntax#comments-and-metadata).
+
 The Azure deployment template can take a few minutes to complete. When it finishes, you see a message that includes the result:
 
 ```output
@@ -268,9 +270,20 @@ az deployment group create \
   --parameters '@storage.parameters.json'
 ```
 
-## Handle extended JSON format
+## Comments and the extended JSON format
+
+You can include `//` style comments in your parameter file, but you must name the file with a `.jsonc` extension.
+
+```azurecli-interactive
+az deployment group create \
+  --name ExampleDeployment \
+  --resource-group ExampleGroup \
+  --template-file storage.json \
+  --parameters '@storage.parameters.jsonc'
+```
+For more details about comments and metadata see [Understand the structure and syntax of ARM templates](/azure/azure-resource-manager/templates/syntax#comments-and-metadata).
 
-To deploy a template with multi-line strings or comments using Azure CLI with version 2.3.0 or older, you must use the `--handle-extended-json-format` switch.  For example:
+If you are using Azure CLI with version 2.3.0 or older, you can deploy a template with multi-line strings or comments using the `--handle-extended-json-format` switch.  For example:
 
 ```json
 {