Merge pull request #104288 from tfitzmac/0213funcs

add function scope

Author: megvanhuygen

articles/azure-resource-manager/templates/template-expressions.md

@@ -2,7 +2,7 @@
 title: Template syntax and expressions
 description: Describes the declarative JSON syntax for Azure Resource Manager templates.
 ms.topic: conceptual
-ms.date: 02/10/2020
+ms.date: 02/13/2020
 ---
 
 # Syntax and expressions in Azure Resource Manager templates
@@ -11,11 +11,9 @@ The basic syntax of the template is JSON. However, you can use expressions to ex
 
 A template expression can't exceed 24,576 characters.
 
-Expressions support json('null') and properties support a literal value of null. In both cases, Resource Manager templates treat it as if the property is not present.
-
 ## Use functions
 
-The following example shows an expression in the default value of a parameter:
+Azure Resource Manager provides [functions](template-functions.md) that you can use in a template. The following example shows an expression that uses a function in the default value of a parameter:
 
 ```json
 "parameters": {
@@ -36,6 +34,12 @@ To pass a string value as a parameter to a function, use single quotes.
 "name": "[concat('storage', uniqueString(resourceGroup().id))]"
 ```
 
+Most functions work the same whether deployed to a resource group, subscription, management group, or tenant. The following functions have restrictions based on the scope:
+
+* [resourceGroup](template-functions-resource.md#resourcegroup) - can only be used in deployments to a resource group.
+* [resourceId](template-functions-resource.md#resourceid) - can be used at any scope, but the valid parameters change depending on the scope.
+* [subscription](template-functions-resource.md#subscription) - can only be used in deployments to a resource group or subscription.
+
 ## Escape characters
 
 To have a literal string start with a left bracket `[` and end with a right bracket `]`, but not have it interpreted as an expression, add an extra bracket to start the string with `[[`. For example, the variable:
@@ -62,6 +66,15 @@ To escape double quotes in an expression, such as adding a JSON object in the te
 },
 ```
 
+## Null values
+
+To set a property to null, you can use **null** or **[json('null')]**. The [json function](template-functions-array.md#json) returns an empty object when you provide `null` as the parameter. In both cases, Resource Manager templates treat it as if the property is not present.
+
+```json
+"stringValue": null,
+"objectValue": "[json('null')]"
+```
+
 ## Next steps
 
 * For the full list of template functions, see [Azure Resource Manager template functions](template-functions.md).

articles/azure-resource-manager/templates/template-functions-resource.md

@@ -753,7 +753,7 @@ Returns the unique identifier of a resource. You use this function when the reso
 
 | Parameter | Required | Type | Description |
 |:--- |:--- |:--- |:--- |
-| subscriptionId |No |string (In GUID format) |Default value is the current subscription. Specify this value when you need to retrieve a resource in another subscription. |
+| subscriptionId |No |string (In GUID format) |Default value is the current subscription. Specify this value when you need to retrieve a resource in another subscription. Only provide this value when deploying at the scope of a resource group or subscription. |
 | resourceGroupName |No |string |Default value is current resource group. Specify this value when you need to retrieve a resource in another resource group. Only provide this value when deploying at the scope of a resource group. |
 | resourceType |Yes |string |Type of resource including resource provider namespace. |
 | resourceName1 |Yes |string |Name of resource. |

articles/azure-resource-manager/templates/template-functions.md

@@ -2,14 +2,16 @@
 title: Template functions
 description: Describes the functions to use in an Azure Resource Manager template to retrieve values, work with strings and numerics, and retrieve deployment information.
 ms.topic: conceptual
-ms.date: 11/19/2019
+ms.date: 02/13/2020
 ---
 # Azure Resource Manager template functions
 
 This article describes all the functions you can use in an Azure Resource Manager template. For information about using functions in your template, see [template syntax](template-expressions.md).
 
 To create your own functions, see [User-defined functions](template-syntax.md#functions).
 
+Most functions work the same when deployed to a resource group, subscription, management group, or tenant. A few functions can't be used in all scopes. They're noted in the lists below.
+
 <a id="array" aria-hidden="true" />
 <a id="coalesce" aria-hidden="true" />
 <a id="concatarray" aria-hidden="true" />
@@ -29,6 +31,7 @@ To create your own functions, see [User-defined functions](template-syntax.md#fu
 <a id="union" aria-hidden="true" />
 
 ## Array and object functions
+
 Resource Manager provides several functions for working with arrays and objects.
 
 * [array](template-functions-array.md#array)
@@ -56,6 +59,7 @@ Resource Manager provides several functions for working with arrays and objects.
 <a id="greaterorequals" aria-hidden="true" />
 
 ## Comparison functions
+
 Resource Manager provides several functions for making comparisons in your templates.
 
 * [equals](template-functions-comparison.md#equals)
@@ -69,6 +73,7 @@ Resource Manager provides several functions for making comparisons in your templ
 <a id="variables" aria-hidden="true" />
 
 ## Deployment value functions
+
 Resource Manager provides the following functions for getting values from sections of the template and values related to the deployment:
 
 * [deployment](template-functions-deployment.md#deployment)
@@ -83,6 +88,7 @@ Resource Manager provides the following functions for getting values from sectio
 <a id="or" aria-hidden="true" />
 
 ## Logical functions
+
 Resource Manager provides the following functions for working with logical conditions:
 
 * [and](template-functions-logical.md#and)
@@ -103,6 +109,7 @@ Resource Manager provides the following functions for working with logical condi
 <a id="sub" aria-hidden="true" />
 
 ## Numeric functions
+
 Resource Manager provides the following functions for working with integers:
 
 * [add](template-functions-numeric.md#add)
@@ -128,6 +135,7 @@ Resource Manager provides the following functions for working with integers:
 <a id="tenantResourceId" aria-hidden="true" />
 
 ## Resource functions
+
 Resource Manager provides the following functions for getting resource values:
 
 * [extensionResourceId](template-functions-resource.md#extensionresourceid)
@@ -137,9 +145,9 @@ Resource Manager provides the following functions for getting resource values:
 * [list*](template-functions-resource.md#list)
 * [providers](template-functions-resource.md#providers)
 * [reference](template-functions-resource.md#reference)
-* [resourceGroup](template-functions-resource.md#resourcegroup)
-* [resourceId](template-functions-resource.md#resourceid)
-* [subscription](template-functions-resource.md#subscription)
+* [resourceGroup](template-functions-resource.md#resourcegroup) - can only be used in deployments to a resource group.
+* [resourceId](template-functions-resource.md#resourceid) - can be used at any scope, but the valid parameters change depending on the scope.
+* [subscription](template-functions-resource.md#subscription) - can only be used in deployments to a resource group or subscription.
 * [subscriptionResourceId](template-functions-resource.md#subscriptionresourceid)
 * [tenantResourceId](template-functions-resource.md#tenantresourceid)
 
@@ -175,6 +183,7 @@ Resource Manager provides the following functions for getting resource values:
 <a id="uricomponenttostring" aria-hidden="true" />
 
 ## String functions
+
 Resource Manager provides the following functions for working with strings:
 
 * [base64](template-functions-string.md#base64)