Updated 06-convert-arm-template.md (#1074)

docs/tutorial/06-convert-arm-template.md

@@ -2,14 +2,78 @@
 
 **assumes that the ARM template only uses [syntax that is supported](../spec) in Bicep*
 
-Since Bicep is a transparent abstraction of ARM templates, any resource that can be deployed via an ARM template can be authored in Bicep. However, not all ARM template capabilities are supported in Bicep in the 0.1 release. The following statements must be true in order for the template to be convertible:
+Since Bicep is a transparent abstraction of ARM templates, any resource that can be deployed via an ARM template can be authored in Bicep. However, not all ARM template capabilities are supported in Bicep in the 0.2 release. The following statements must be true in order for the template to be convertible:
 
 * Template does *not* use the `copy` function for creating multiple resources, multiple variables, or multiple outputs
 * Template does *not* conditionally deploy resources with the `condition` property
-* Template does not deploy across scopes (though this can be hacked together by using the `Microsoft.Resources/deployments` resource and using the `templateLink` or `template` property to insert the full ARM template)
 
+## Decompiling an ARM Template
+> Requires Bicep CLI v0.2.59 or later
+ 
+The Bicep CLI provides the ability to [decompile](../decompiling.md) any existing ARM Template to a `.bicep` file, using the `bicep decompile` command.
 
-## Convert parameters, variables, and outputs
+Here's an example ARM Template that deploys a storage account.
+
+```json
+{
+    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+    "contentVersion": "1.0.0.0",
+    "parameters": {
+        "location": {
+            "defaultValue": "[resourceGroup().location]",
+            "type": "String"
+        },
+        "namePrefix": {
+            "defaultValue": "contoso",
+            "type": "String"
+        },
+        "production": {
+            "defaultValue": false,
+            "type": "bool"
+        }
+    },
+    "variables": {
+        "storageName": "[concat(parameters('nameprefix'), uniqueString(resourceGroup().id),'st')]"
+    },
+    "resources": [
+        {
+            "type": "Microsoft.Storage/storageAccounts",
+            "apiVersion": "2019-06-01",
+            "name": "[variables('storageName')]",
+            "location": "[parameters('location')]",
+            "kind": "Storage",
+            "sku": {
+                "name": "[if(parameters('production'), 'Standard_ZRS', 'Standard_LRS')]"
+            }
+        }
+    ]
+}
+```
+
+Let's decompile the ARM template with `bicep decompile ".\storage.json"` and look at the output `.bicep` file.
+
+```
+param location string = resourceGroup().location
+param namePrefix string = 'contoso'
+param production bool = false
+
+var storageName_var = '${namePrefix}${uniqueString(resourceGroup().id)}st'
+
+resource storageName 'Microsoft.Storage/storageAccounts@2019-06-01' = {
+  name: storageName_var
+  location: location
+  kind: 'Storage'
+  sku: {
+    name: (production ? 'Standard_ZRS' : 'Standard_LRS')
+  }
+}
+```
+
+Now we have a good starting point for continued Bicep authoring. Note that the variable `storagename` have changed to `storageName_var` and the symbolic name for the storage account resource is set to `storagename` based on the variable name used for the storage name in the ARM Template.
+
+> Decompilation is a best-effort process, as there is no guaranteed mapping from ARM JSON to Bicep. You may need to fix warnings and errors in the generated bicep file(s), or decompilation may fail entirely if an accurate conversion is not possible. If you would like to report any issues or inaccurate conversions, please see https://github.com/Azure/bicep/issues.
+
+## Manually convert parameters, variables, and outputs
 
 Parameter, variable and output declarations are relatively simple to convert. Let's look at some code samples and convert them into Bicep syntax:
 
@@ -187,10 +251,10 @@ resource vnet 'Microsoft.Network/virtualNetworks@2018-10-01' = {
 }
 ```
 
-## Convert an entire ARM template
+## Sample templates
 
 You can take a look at an entire sample template converted to a bicep file here:
 
 [ARM Template](./complete-bicep-files/05.json) -> [Bicep file](./complete-bicep-files/05.bicep)
 
-We also have a growing set of [examples](../examples) of fully converted [Azure QuickStart templates](https://github.com/Azure/azure-quickstart-templates)
+We also have a growing set of [examples](../examples) of fully converted [Azure QuickStart templates](https://github.com/Azure/azure-quickstart-templates).