On branch edburns-msft-96155-jsonc-mention https://dev.azure.com/edburns-msft/Open%20Standard%20Enterprise%20Java%20(Java%20EE)%20on%20Azure/_workitems/edit/1968 https://github.com/MicrosoftDocs/azure-docs/issues/96155

modified:   articles/azure-resource-manager/templates/best-practices.md
modified:   articles/azure-resource-manager/templates/deploy-cli.md

Signed-off-by: Ed Burns <[email protected]>

Author: edburns

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

@@ -189,6 +189,21 @@ 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]",
+          ...
+      }
+    ]
+    ```
+
 * 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 +287,10 @@ 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, if your ARM template is stored in a `.jsonc` file, comments using the `//` syntax are supported.
+
 ## 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 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,19 @@ 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'
+```
 
-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
 {