Edit

String functions for ARM templates

  • Article

Resource Manager provides the following functions for working with strings in your Azure Resource Manager template (ARM template):

Tip

We recommend Bicep because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see string functions.

base64

base64(inputString)

Returns the base64 representation of the input string.

In Bicep, use the base64 function.

Parameters

Parameter Required Type Description
inputString Yes string The value to return as a base64 representation.

Return value

A string containing the base64 representation.

Examples

The following example shows how to use the base64 function.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringData": {
      "type": "string",
      "defaultValue": "one, two, three"
    },
    "jsonFormattedData": {
      "type": "string",
      "defaultValue": "{'one': 'a', 'two': 'b'}"
    }
  },
  "variables": {
    "base64String": "[base64(parameters('stringData'))]",
    "base64Object": "[base64(parameters('jsonFormattedData'))]"
  },
  "resources": [
  ],
  "outputs": {
    "base64Output": {
      "type": "string",
      "value": "[variables('base64String')]"
    },
    "toStringOutput": {
      "type": "string",
      "value": "[base64ToString(variables('base64String'))]"
    },
    "toJsonOutput": {
      "type": "object",
      "value": "[base64ToJson(variables('base64Object'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
base64Output String b25lLCB0d28sIHRocmVl
toStringOutput String one, two, three
toJsonOutput Object {"one": "a", "two": "b"}

base64ToJson

base64ToJson(base64Value)

Converts a base64 representation to a JSON object.

In Bicep, use the base64ToJson function.

Parameters

Parameter Required Type Description
base64Value Yes string The base64 representation to convert to a JSON object.

Return value

A JSON object.

Examples

The following example uses the base64ToJson function to convert a base64 value:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringData": {
      "type": "string",
      "defaultValue": "one, two, three"
    },
    "jsonFormattedData": {
      "type": "string",
      "defaultValue": "{'one': 'a', 'two': 'b'}"
    }
  },
  "variables": {
    "base64String": "[base64(parameters('stringData'))]",
    "base64Object": "[base64(parameters('jsonFormattedData'))]"
  },
  "resources": [
  ],
  "outputs": {
    "base64Output": {
      "type": "string",
      "value": "[variables('base64String')]"
    },
    "toStringOutput": {
      "type": "string",
      "value": "[base64ToString(variables('base64String'))]"
    },
    "toJsonOutput": {
      "type": "object",
      "value": "[base64ToJson(variables('base64Object'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
base64Output String b25lLCB0d28sIHRocmVl
toStringOutput String one, two, three
toJsonOutput Object {"one": "a", "two": "b"}

base64ToString

base64ToString(base64Value)

Converts a base64 representation to a string.

In Bicep, use the base64ToString function.

Parameters

Parameter Required Type Description
base64Value Yes string The base64 representation to convert to a string.

Return value

A string of the converted base64 value.

Examples

The following example uses the base64ToString function to convert a base64 value:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringData": {
      "type": "string",
      "defaultValue": "one, two, three"
    },
    "jsonFormattedData": {
      "type": "string",
      "defaultValue": "{'one': 'a', 'two': 'b'}"
    }
  },
  "variables": {
    "base64String": "[base64(parameters('stringData'))]",
    "base64Object": "[base64(parameters('jsonFormattedData'))]"
  },
  "resources": [
  ],
  "outputs": {
    "base64Output": {
      "type": "string",
      "value": "[variables('base64String')]"
    },
    "toStringOutput": {
      "type": "string",
      "value": "[base64ToString(variables('base64String'))]"
    },
    "toJsonOutput": {
      "type": "object",
      "value": "[base64ToJson(variables('base64Object'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
base64Output String b25lLCB0d28sIHRocmVl
toStringOutput String one, two, three
toJsonOutput Object {"one": "a", "two": "b"}

concat

concat(arg1, arg2, arg3, ...)

Combines multiple string values and returns the concatenated string, or combines multiple arrays and returns the concatenated array.

In Bicep, use string interpolation instead of the concat() function to improve readability. However, in some cases such as string replacement in multi-line strings, you may need to fall back on using the concat() function or the replace() function.

Parameters

Parameter Required Type Description
arg1 Yes string or array The first string or array for concatenation.
more arguments No string or array More strings or arrays in sequential order for concatenation.

This function can take any number of arguments, and can accept either strings or arrays for the parameters. However, you can't provide both arrays and strings for parameters. Strings are only concatenated with other strings.

Return value

A string or array of concatenated values.

Examples

The following example shows how to combine two string values and return a concatenated string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string",
      "defaultValue": "prefix"
    }
  },
  "resources": [],
  "outputs": {
    "concatOutput": {
      "type": "string",
      "value": "[concat(parameters('prefix'), '-', uniqueString(resourceGroup().id))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
concatOutput String prefix-5yj4yjf5mbg72

The following example shows how to combine two arrays.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstArray": {
      "type": "array",
      "defaultValue": [
        "1-1",
        "1-2",
        "1-3"
      ]
    },
    "secondArray": {
      "type": "array",
      "defaultValue": [
        "2-1",
        "2-2",
        "2-3"
      ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "return": {
      "type": "array",
      "value": "[concat(parameters('firstArray'), parameters('secondArray'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
return Array ["1-1", "1-2", "1-3", "2-1", "2-2", "2-3"]

contains

contains(container, itemToFind)

Checks whether an array contains a value, an object contains a key, or a string contains a substring. The string comparison is case-sensitive. However, when testing if an object contains a key, the comparison is case-insensitive.

In Bicep, use the contains function.

Parameters

Parameter Required Type Description
container Yes array, object, or string The value that contains the value to find.
itemToFind Yes string or int The value to find.

Return value

True if the item is found; otherwise, False.

Examples

The following example shows how to use contains with different types:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringToTest": {
      "type": "string",
      "defaultValue": "OneTwoThree"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b",
        "three": "c"
      }
    },
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "stringTrue": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'e')]"
    },
    "stringFalse": {
      "type": "bool",
      "value": "[contains(parameters('stringToTest'), 'z')]"
    },
    "objectTrue": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'one')]"
    },
    "objectFalse": {
      "type": "bool",
      "value": "[contains(parameters('objectToTest'), 'a')]"
    },
    "arrayTrue": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'three')]"
    },
    "arrayFalse": {
      "type": "bool",
      "value": "[contains(parameters('arrayToTest'), 'four')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
stringTrue Bool True
stringFalse Bool False
objectTrue Bool True
objectFalse Bool False
arrayTrue Bool True
arrayFalse Bool False

dataUri

dataUri(stringToConvert)

Converts a value to a data URI.

In Bicep, use the dataUri function.

Parameters

Parameter Required Type Description
stringToConvert Yes string The value to convert to a data URI.

Return value

A string formatted as a data URI.

Examples

The following example converts a value to a data URI, and converts a data URI to a string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringToTest": {
      "type": "string",
      "defaultValue": "Hello"
    },
    "dataFormattedString": {
      "type": "string",
      "defaultValue": "data:;base64,SGVsbG8sIFdvcmxkIQ=="
    }
  },
  "resources": [],
  "outputs": {
    "dataUriOutput": {
      "value": "[dataUri(parameters('stringToTest'))]",
      "type": "string"
    },
    "toStringOutput": {
      "type": "string",
      "value": "[dataUriToString(parameters('dataFormattedString'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
dataUriOutput String data:text/plain;charset=utf8;base64,SGVsbG8=
toStringOutput String Hello, World!

dataUriToString

dataUriToString(dataUriToConvert)

Converts a data URI formatted value to a string.

In Bicep, use the dataUriToString function.

Parameters

Parameter Required Type Description
dataUriToConvert Yes string The data URI value to convert.

Return value

A string containing the converted value.

Examples

The following example template converts a value to a data URI, and converts a data URI to a string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringToTest": {
      "type": "string",
      "defaultValue": "Hello"
    },
    "dataFormattedString": {
      "type": "string",
      "defaultValue": "data:;base64,SGVsbG8sIFdvcmxkIQ=="
    }
  },
  "resources": [],
  "outputs": {
    "dataUriOutput": {
      "value": "[dataUri(parameters('stringToTest'))]",
      "type": "string"
    },
    "toStringOutput": {
      "type": "string",
      "value": "[dataUriToString(parameters('dataFormattedString'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
dataUriOutput String data:text/plain;charset=utf8;base64,SGVsbG8=
toStringOutput String Hello, World!

empty

empty(itemToTest)

Determines if an array, object, or string is empty.

In Bicep, use the empty function.

Parameters

Parameter Required Type Description
itemToTest Yes array, object, or string The value to check if it's empty.

Return value

Returns True if the value is empty; otherwise, False.

Examples

The following example checks whether an array, object, and string are empty.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": []
    },
    "testObject": {
      "type": "object",
      "defaultValue": {}
    },
    "testString": {
      "type": "string",
      "defaultValue": ""
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testArray'))]"
    },
    "objectEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testObject'))]"
    },
    "stringEmpty": {
      "type": "bool",
      "value": "[empty(parameters('testString'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayEmpty Bool True
objectEmpty Bool True
stringEmpty Bool True

endsWith

endsWith(stringToSearch, stringToFind)

Determines whether a string ends with a value. The comparison is case-insensitive.

In Bicep, use the endsWith function.

Parameters

Parameter Required Type Description
stringToSearch Yes string The value that contains the item to find.
stringToFind Yes string The value to find.

Return value

True if the last character or characters of the string match the value; otherwise, False.

Examples

The following example shows how to use the startsWith and endsWith functions:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "startsTrue": {
      "type": "bool",
      "value": "[startsWith('abcdef', 'ab')]"
    },
    "startsCapTrue": {
      "type": "bool",
      "value": "[startsWith('abcdef', 'A')]"
    },
    "startsFalse": {
      "type": "bool",
      "value": "[startsWith('abcdef', 'e')]"
    },
    "endsTrue": {
      "type": "bool",
      "value": "[endsWith('abcdef', 'ef')]"
    },
    "endsCapTrue": {
      "type": "bool",
      "value": "[endsWith('abcdef', 'F')]"
    },
    "endsFalse": {
      "type": "bool",
      "value": "[endsWith('abcdef', 'e')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
startsTrue Bool True
startsCapTrue Bool True
startsFalse Bool False
endsTrue Bool True
endsCapTrue Bool True
endsFalse Bool False

first

first(arg1)

Returns the first character of the string, or first element of the array. If an empty string is given, the function results in an empty string. In the case of an empty array, the function returns null.

In Bicep, use the first function.

Parameters

Parameter Required Type Description
arg1 Yes array or string The value to retrieve the first element or character.

Return value

A string of the first character, or the type (string, int, array, or object) of the first element in an array.

Examples

The following example shows how to use the first function with an array and string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayOutput": {
      "type": "string",
      "value": "[first(parameters('arrayToTest'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[first('One Two Three')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput String one
stringOutput String O

format

format(formatString, arg1, arg2, ...)

Creates a formatted string from input values.

In Bicep, use the format function.

Parameters

Parameter Required Type Description
formatString Yes string The composite format string.
arg1 Yes string, integer, or boolean The value to include in the formatted string.
more arguments No string, integer, or boolean More values to include in the formatted string.

Remarks

Use this function to format a string in your template. It uses the same formatting options as the System.String.Format method in .NET.

Examples

The following example shows how to use the format function.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "greeting": {
      "type": "string",
      "defaultValue": "Hello"
    },
    "name": {
      "type": "string",
      "defaultValue": "User"
    },
    "numberToFormat": {
      "type": "int",
      "defaultValue": 8175133
    }
  },
  "resources": [
  ],
  "outputs": {
    "formatTest": {
      "type": "string",
      "value": "[format('{0}, {1}. Formatted number: {2:N0}', parameters('greeting'), parameters('name'), parameters('numberToFormat'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
formatTest String Hello, User. Formatted number: 8,175,133

guid

guid(baseString, ...)

Creates a value in the format of a globally unique identifier based on the values provided as parameters.

In Bicep, use the guid function.

Parameters

Parameter Required Type Description
baseString Yes string The value used in the hash function to create the GUID.
more parameters as needed No string You can add as many strings as needed to create the value that specifies the level of uniqueness.

Remarks

This function is helpful when you need to create a value in the format of a globally unique identifier. You provide parameter values that limit the scope of uniqueness for the result. You can specify whether the name is unique down to subscription, resource group, or deployment.

The returned value isn't a random string, but rather the result of a hash function on the parameters. The returned value is 36 characters long. It isn't globally unique. To create a new GUID that isn't based on that hash value of the parameters, use the newGuid function.

The following examples show how to use guid to create a unique value for commonly used levels.

Unique scoped to subscription

"[guid(subscription().subscriptionId)]"

Unique scoped to resource group

"[guid(resourceGroup().id)]"

Unique scoped to deployment for a resource group

"[guid(resourceGroup().id, deployment().name)]"

The guid function implements the algorithm from RFC 4122 ยง4.3. The original source can be found in GuidUtility with some modifications.

Return value

A string containing 36 characters in the format of a globally unique identifier.

Examples

The following example returns results from guid:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {},
  "resources": [],
  "outputs": {
    "guidPerSubscription": {
      "type": "string",
      "value": "[guid(subscription().subscriptionId)]"
    },
    "guidPerResourceGroup": {
      "type": "string",
      "value": "[guid(resourceGroup().id)]"
    },
    "guidPerDeployment": {
      "type": "string",
      "value": "[guid(resourceGroup().id, deployment().name)]"
    }
  }
}

indexOf

indexOf(stringToSearch, stringToFind)

Returns the first position of a value within a string. The comparison is case-insensitive.

In Bicep, use the indexOf function.

Parameters

Parameter Required Type Description
stringToSearch Yes string The value that contains the item to find.
stringToFind Yes string The value to find.

Return value

An integer that represents the position of the item to find. The value is zero-based. If the item isn't found, -1 is returned.

Examples

The following example shows how to use the indexOf and lastIndexOf functions:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "firstT": {
      "type": "int",
      "value": "[indexOf('test', 't')]"
    },
    "lastT": {
      "type": "int",
      "value": "[lastIndexOf('test', 't')]"
    },
    "firstString": {
      "type": "int",
      "value": "[indexOf('abcdef', 'CD')]"
    },
    "lastString": {
      "type": "int",
      "value": "[lastIndexOf('abcdef', 'AB')]"
    },
    "notFound": {
      "type": "int",
      "value": "[indexOf('abcdef', 'z')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
firstT Int 0
lastT Int 3
firstString Int 2
lastString Int 0
notFound Int -1

join

join(inputArray, delimiter)

Joins a string array into a single string, separated using a delimiter.

In Bicep, use the join function.

Parameters

Parameter Required Type Description
inputArray Yes array of string An array of string to join.
delimiter Yes The delimiter to use for splitting the string.

Return value

A string.

Examples

The following example joins the input string array into strings delimited by using different delimiters.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "arrayString": [
      "one",
      "two",
      "three"
    ]
  },
  "resources": [],
  "outputs": {
    "firstOutput": {
      "type": "string",
      "value": "[join(variables('arrayString'), ',')]"
    },
    "secondOutput": {
      "type": "string",
      "value": "[join(variables('arrayString'), ';')]"
    }
  }
}

The output from the preceding example is:

Name Type Value
firstOutput String "one,two,three"
secondOutput String "one;two;three"

json

json(arg1)

Converts a valid JSON string into a JSON data type. For more information, see json function.

In Bicep, use the json function.

last

last(arg1)

Returns last character of the string, or the last element of the array.

In Bicep, use the last function.

Parameters

Parameter Required Type Description
arg1 Yes array or string The value to retrieve the last element or character.

Return value

A string of the last character, or the type (string, int, array, or object) of the last element in an array.

Examples

The following example shows how to use the last function with an array and string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [ "one", "two", "three" ]
    }
  },
  "resources": [
  ],
  "outputs": {
    "arrayOutput": {
      "type": "string",
      "value": "[last(parameters('arrayToTest'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[last('One Two Three')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput String three
stringOutput String e

lastIndexOf

lastIndexOf(stringToSearch, stringToFind)

Returns the last position of a value within a string. The comparison is case-insensitive.

In Bicep, use the lastIndexOf function.

Parameters

Parameter Required Type Description
stringToSearch Yes string The value that contains the item to find.
stringToFind Yes string The value to find.

Return value

An integer that represents the last position of the item to find. The value is zero-based. If the item isn't found, -1 is returned.

Examples

The following example shows how to use the indexOf and lastIndexOf functions:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "firstT": {
      "type": "int",
      "value": "[indexOf('test', 't')]"
    },
    "lastT": {
      "type": "int",
      "value": "[lastIndexOf('test', 't')]"
    },
    "firstString": {
      "type": "int",
      "value": "[indexOf('abcdef', 'CD')]"
    },
    "lastString": {
      "type": "int",
      "value": "[lastIndexOf('abcdef', 'AB')]"
    },
    "notFound": {
      "type": "int",
      "value": "[indexOf('abcdef', 'z')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
firstT Int 0
lastT Int 3
firstString Int 2
lastString Int 0
notFound Int -1

length

length(string)

Returns the number of characters in a string, elements in an array, or root-level properties in an object.

In Bicep, use the length function.

Parameters

Parameter Required Type Description
arg1 Yes array, string, or object The array to use for getting the number of elements, the string to use for getting the number of characters, or the object to use for getting the number of root-level properties.

Return value

An int.

Examples

The following example shows how to use the length function with an array and string:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "arrayToTest": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "stringToTest": {
      "type": "string",
      "defaultValue": "One Two Three"
    },
    "objectToTest": {
      "type": "object",
      "defaultValue": {
        "propA": "one",
        "propB": "two",
        "propC": "three",
        "propD": {
          "propD-1": "sub",
          "propD-2": "sub"
        }
      }
    }
  },
  "resources": [],
  "outputs": {
    "arrayLength": {
      "type": "int",
      "value": "[length(parameters('arrayToTest'))]"
    },
    "stringLength": {
      "type": "int",
      "value": "[length(parameters('stringToTest'))]"
    },
    "objectLength": {
      "type": "int",
      "value": "[length(parameters('objectToTest'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayLength Int 3
stringLength Int 13
objectLength Int 4

newGuid

newGuid()

Returns a value in the format of a globally unique identifier. This function can only be used in the default value for a parameter.

In Bicep, use the newGuid function.

Remarks

You can only use this function within an expression for the default value of a parameter. Using this function anywhere else in a template returns an error. The function isn't allowed in other parts of the template because it returns a different value each time it's called. Deploying the same template with the same parameters wouldn't reliably produce the same results.

The newGuid function differs from the guid function because it doesn't take any parameters. When you call guid with the same parameter, it returns the same identifier each time. Use guid when you need to reliably generate the same GUID for a specific environment. Use newGuid when you need a different identifier each time, such as deploying resources to a test environment.

The newGuid function uses the Guid structure in the .NET Framework to generate the globally unique identifier.

If you use the option to redeploy an earlier successful deployment, and the earlier deployment includes a parameter that uses newGuid, the parameter isn't reevaluated. Instead, the parameter value from the earlier deployment is automatically reused in the rollback deployment.

In a test environment, you may need to repeatedly deploy resources that only live for a short time. Rather than constructing unique names, you can use newGuid with uniqueString to create unique names.

Be careful redeploying a template that relies on the newGuid function for a default value. When you redeploy and don't provide a value for the parameter, the function is reevaluated. If you want to update an existing resource rather than create a new one, pass in the parameter value from the earlier deployment.

Return value

A string containing 36 characters in the format of a globally unique identifier.

Examples

The following example shows a parameter with a new identifier.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "guidValue": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "resources": [
  ],
  "outputs": {
    "guidOutput": {
      "type": "string",
      "value": "[parameters('guidValue')]"
    }
  }
}

The output from the preceding example varies for each deployment but will be similar to:

Name Type Value
guidOutput string b76a51fc-bd72-4a77-b9a2-3c29e7d2e551

The following example uses the newGuid function to create a unique name for a storage account. This template might work for test environment where the storage account exists for a short time and isn't redeployed.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "guidValue": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    "storageName": "[concat('storage', uniqueString(parameters('guidValue')))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageName')]",
      "location": "West US",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "nameOutput": {
      "type": "string",
      "value": "[variables('storageName')]"
    }
  }
}

The output from the preceding example varies for each deployment but will be similar to:

Name Type Value
nameOutput string storagenziwvyru7uxie

padLeft

padLeft(valueToPad, totalLength, paddingCharacter)

Returns a right-aligned string by adding characters to the left until reaching the total specified length.

In Bicep, use the padLeft function.

Parameters

Parameter Required Type Description
valueToPad Yes string or int The value to right-align.
totalLength Yes int The total number of characters in the returned string.
paddingCharacter No single character The character to use for left-padding until the total length is reached. The default value is a space.

If the original string is longer than the number of characters to pad, no characters are added.

Return value

A string with at least the number of specified characters.

Examples

The following example shows how to pad the user-provided parameter value by adding the zero character until it reaches the total number of characters.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testString": {
      "type": "string",
      "defaultValue": "123"
    }
  },
  "resources": [],
  "outputs": {
    "stringOutput": {
      "type": "string",
      "value": "[padLeft(parameters('testString'),10,'0')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
stringOutput String 0000000123

replace

replace(originalString, oldString, newString)

Returns a new string with all instances of one string replaced by another string.

In Bicep, use the replace function.

Parameters

Parameter Required Type Description
originalString Yes string The value that has all instances of one string replaced by another string.
oldString Yes string The string to be removed from the original string.
newString Yes string The string to add in place of the removed string.

Return value

A string with the replaced characters.

Examples

The following example shows how to remove all dashes from the user-provided string, and how to replace part of the string with another string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testString": {
      "type": "string",
      "defaultValue": "123-123-1234"
    }
  },
  "resources": [],
  "outputs": {
    "firstOutput": {
      "type": "string",
      "value": "[replace(parameters('testString'),'-', '')]"
    },
    "secondOutput": {
      "type": "string",
      "value": "[replace(parameters('testString'),'1234', 'xxxx')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
firstOutput String 1231231234
secondOutput String 123-123-xxxx

skip

skip(originalValue, numberToSkip)

Returns a string with all the characters after the specified number of characters, or an array with all the elements after the specified number of elements.

In Bicep, use the skip function.

Parameters

Parameter Required Type Description
originalValue Yes array or string The array or string to use for skipping.
numberToSkip Yes int The number of elements or characters to skip. If this value is 0 or less, all the elements or characters in the value are returned. If it's larger than the length of the array or string, an empty array or string is returned.

Return value

An array or string.

Examples

The following example skips the specified number of elements in the array, and the specified number of characters in a string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "elementsToSkip": {
      "type": "int",
      "defaultValue": 2
    },
    "testString": {
      "type": "string",
      "defaultValue": "one two three"
    },
    "charactersToSkip": {
      "type": "int",
      "defaultValue": 4
    }
  },
  "resources": [],
  "outputs": {
    "arrayOutput": {
      "type": "array",
      "value": "[skip(parameters('testArray'),parameters('elementsToSkip'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[skip(parameters('testString'),parameters('charactersToSkip'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput Array ["three"]
stringOutput String two three

split

split(inputString, delimiter)

Returns an array of strings that contains the substrings of the input string that are delimited by the specified delimiters.

In Bicep, use the split function.

Parameters

Parameter Required Type Description
inputString Yes string The string to split.
delimiter Yes string or array of strings The delimiter to use for splitting the string.

Return value

An array of strings.

Examples

The following example splits the input string with a comma, and with either a comma or a semicolon.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "firstString": {
      "type": "string",
      "defaultValue": "one,two,three"
    },
    "secondString": {
      "type": "string",
      "defaultValue": "one;two,three"
    }
  },
  "variables": {
    "delimiters": [ ",", ";" ]
  },
  "resources": [],
  "outputs": {
    "firstOutput": {
      "type": "array",
      "value": "[split(parameters('firstString'),',')]"
    },
    "secondOutput": {
      "type": "array",
      "value": "[split(parameters('secondString'),variables('delimiters'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
firstOutput Array ["one", "two", "three"]
secondOutput Array ["one", "two", "three"]

startsWith

startsWith(stringToSearch, stringToFind)

Determines whether a string starts with a value. The comparison is case-insensitive.

In Bicep, use the startsWith function.

Parameters

Parameter Required Type Description
stringToSearch Yes string The value that contains the item to find.
stringToFind Yes string The value to find.

Return value

True if the first character or characters of the string match the value; otherwise, False.

Examples

The following example shows how to use the startsWith and endsWith functions:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "startsTrue": {
      "type": "bool",
      "value": "[startsWith('abcdef', 'ab')]"
    },
    "startsCapTrue": {
      "type": "bool",
      "value": "[startsWith('abcdef', 'A')]"
    },
    "startsFalse": {
      "type": "bool",
      "value": "[startsWith('abcdef', 'e')]"
    },
    "endsTrue": {
      "type": "bool",
      "value": "[endsWith('abcdef', 'ef')]"
    },
    "endsCapTrue": {
      "type": "bool",
      "value": "[endsWith('abcdef', 'F')]"
    },
    "endsFalse": {
      "type": "bool",
      "value": "[endsWith('abcdef', 'e')]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
startsTrue Bool True
startsCapTrue Bool True
startsFalse Bool False
endsTrue Bool True
endsCapTrue Bool True
endsFalse Bool False

string

string(valueToConvert)

Converts the specified value to a string.

In Bicep, use the string function.

Parameters

Parameter Required Type Description
valueToConvert Yes Any The value to convert to string. Any type of value can be converted, including objects and arrays.

Return value

A string of the converted value.

Examples

The following example shows how to convert different types of values to strings.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testObject": {
      "type": "object",
      "defaultValue": {
        "valueA": 10,
        "valueB": "Example Text"
      }
    },
    "testArray": {
      "type": "array",
      "defaultValue": [
        "a",
        "b",
        "c"
      ]
    },
    "testInt": {
      "type": "int",
      "defaultValue": 5
    }
  },
  "resources": [],
  "outputs": {
    "objectOutput": {
      "type": "string",
      "value": "[string(parameters('testObject'))]"
    },
    "arrayOutput": {
      "type": "string",
      "value": "[string(parameters('testArray'))]"
    },
    "intOutput": {
      "type": "string",
      "value": "[string(parameters('testInt'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
objectOutput String {"valueA":10,"valueB":"Example Text"}
arrayOutput String ["a","b","c"]
intOutput String 5

substring

substring(stringToParse, startIndex, length)

Returns a substring that starts at the specified character position and contains the specified number of characters.

In Bicep, use the substring function.

Parameters

Parameter Required Type Description
stringToParse Yes string The original string from which the substring is extracted.
startIndex No int The zero-based starting character position for the substring.
length No int The number of characters for the substring. Must refer to a location within the string. Must be zero or greater. If omitted, the remainder of the string from the start position will be returned.

Return value

The substring. Or, an empty string if the length is zero.

Remarks

The function fails when the substring extends beyond the end of the string, or when length is less than zero. The following example fails with the error "The index and length parameters must refer to a location within the string. The index parameter: '0', the length parameter: '11', the length of the string parameter: '10'.".

"parameters": {
  "inputString": {
    "type": "string",
    "value": "1234567890"
  }
}, "variables": {
  "prefix": "[substring(parameters('inputString'), 0, 11)]"
}

Examples

The following example extracts a substring from a parameter.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testString": {
      "type": "string",
      "defaultValue": "one two three"
    }
  },
  "resources": [],
  "outputs": {
    "substringOutput": {
      "type": "string",
      "value": "[substring(parameters('testString'), 4, 3)]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
substringOutput String two

take

take(originalValue, numberToTake)

Returns an array or string. An array has the specified number of elements from the start of the array. A string has the specified number of characters from the start of the string.

In Bicep, use the take function.

Parameters

Parameter Required Type Description
originalValue Yes array or string The array or string to take the elements from.
numberToTake Yes int The number of elements or characters to take. If this value is 0 or less, an empty array or string is returned. If it's larger than the length of the given array or string, all the elements in the array or string are returned.

Return value

An array or string.

Examples

The following example takes the specified number of elements from the array, and characters from a string.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testArray": {
      "type": "array",
      "defaultValue": [
        "one",
        "two",
        "three"
      ]
    },
    "elementsToTake": {
      "type": "int",
      "defaultValue": 2
    },
    "testString": {
      "type": "string",
      "defaultValue": "one two three"
    },
    "charactersToTake": {
      "type": "int",
      "defaultValue": 2
    }
  },
  "resources": [],
  "outputs": {
    "arrayOutput": {
      "type": "array",
      "value": "[take(parameters('testArray'),parameters('elementsToTake'))]"
    },
    "stringOutput": {
      "type": "string",
      "value": "[take(parameters('testString'),parameters('charactersToTake'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
arrayOutput Array ["one", "two"]
stringOutput String on

toLower

toLower(stringToChange)

Converts the specified string to lower case.

In Bicep, use the toLower function.

Parameters

Parameter Required Type Description
stringToChange Yes string The value to convert to lower case.

Return value

The string converted to lower case.

Examples

The following example converts a parameter value to lower case and to upper case.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testString": {
      "type": "string",
      "defaultValue": "One Two Three"
    }
  },
  "resources": [],
  "outputs": {
    "toLowerOutput": {
      "type": "string",
      "value": "[toLower(parameters('testString'))]"
    },
    "toUpperOutput": {
      "type": "string",
      "value": "[toUpper(parameters('testString'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
toLowerOutput String one two three
toUpperOutput String ONE TWO THREE

toUpper

toUpper(stringToChange)

Converts the specified string to upper case.

In Bicep, use the toUpper function.

Parameters

Parameter Required Type Description
stringToChange Yes string The value to convert to upper case.

Return value

The string converted to upper case.

Examples

The following example converts a parameter value to lower case and to upper case.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testString": {
      "type": "string",
      "defaultValue": "One Two Three"
    }
  },
  "resources": [],
  "outputs": {
    "toLowerOutput": {
      "type": "string",
      "value": "[toLower(parameters('testString'))]"
    },
    "toUpperOutput": {
      "type": "string",
      "value": "[toUpper(parameters('testString'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
toLowerOutput String one two three
toUpperOutput String ONE TWO THREE

trim

trim(stringToTrim)

Removes all leading and trailing white-space characters from the specified string.

In Bicep, use the trim function.

Parameters

Parameter Required Type Description
stringToTrim Yes string The value to trim.

Return value

The string without leading and trailing white-space characters.

Examples

The following example trims the white-space characters from the parameter.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "testString": {
      "type": "string",
      "defaultValue": "    one two three   "
    }
  },
  "resources": [],
  "outputs": {
    "return": {
      "type": "string",
      "value": "[trim(parameters('testString'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
return String one two three

uniqueString

uniqueString(baseString, ...)

Creates a deterministic hash string based on the values provided as parameters.

In Bicep, use the uniqueString function.

Parameters

Parameter Required Type Description
baseString Yes string The value used in the hash function to create a unique string.
more parameters as needed No string You can add as many strings as needed to create the value that specifies the level of uniqueness.

Remarks

This function is helpful when you need to create a unique name for a resource. You provide parameter values that limit the scope of uniqueness for the result. You can specify whether the name is unique down to subscription, resource group, or deployment.

The returned value isn't a random string, but rather the result of a hash function. The returned value is 13 characters long. It isn't globally unique. You may want to combine the value with a prefix from your naming convention to create a name that is meaningful. The following example shows the format of the returned value. The actual value varies by the provided parameters.

tcvhiyu5h2o5o

The following examples show how to use uniqueString to create a unique value for commonly used levels.

Unique scoped to subscription

"[uniqueString(subscription().subscriptionId)]"

Unique scoped to resource group

"[uniqueString(resourceGroup().id)]"

Unique scoped to deployment for a resource group

"[uniqueString(resourceGroup().id, deployment().name)]"

The following example shows how to create a unique name for a storage account based on your resource group. Inside the resource group, the name isn't unique if constructed the same way.

"resources": [{
  "name": "[concat('storage', uniqueString(resourceGroup().id))]",
  "type": "Microsoft.Storage/storageAccounts",
  ...

If you need to create a new unique name each time you deploy a template, and don't intend to update the resource, you can use the utcNow function with uniqueString. You could use this approach in a test environment. For an example, see utcNow.

Return value

A string containing 13 characters.

Examples

The following example returns results from uniquestring:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "uniqueRG": {
      "type": "string",
      "value": "[uniqueString(resourceGroup().id)]"
    },
    "uniqueDeploy": {
      "type": "string",
      "value": "[uniqueString(resourceGroup().id, deployment().name)]"
    }
  }
}

uri

uri(baseUri, relativeUri)

Creates an absolute URI by combining the baseUri and the relativeUri string.

In Bicep, use the uri function.

Parameters

Parameter Required Type Description
baseUri Yes string The base uri string. Take care to observe the behavior about the handling of the trailing slash (/), as described following this table.
relativeUri Yes string The relative uri string to add to the base uri string.

  • If baseUri ends in a trailing slash, the result is baseUri followed by relativeUri.

  • If baseUri doesn't end in a trailing slash one of two things happens.

    • If baseUri has no slashes at all (aside from the // near the front) the result is baseUri followed by relativeUri.

    • If baseUri has some slashes, but doesn't end with a slash, everything from the last slash onward is removed from baseUri and the result is baseUri followed by relativeUri.

Here are some examples:

uri('http://contoso.org/firstpath', 'myscript.sh') -> http://contoso.org/myscript.sh
uri('http://contoso.org/firstpath/', 'myscript.sh') -> http://contoso.org/firstpath/myscript.sh
uri('http://contoso.org/firstpath/azuredeploy.json', 'myscript.sh') -> http://contoso.org/firstpath/myscript.sh
uri('http://contoso.org/firstpath/azuredeploy.json/', 'myscript.sh') -> http://contoso.org/firstpath/azuredeploy.json/myscript.sh

For complete details, the baseUri and relativeUri parameters are resolved as specified in RFC 3986, section 5.

Return value

A string representing the absolute URI for the base and relative values.

Examples

The following example shows how to construct a link to a nested template based on the value of the parent template.

"templateLink": "[uri(deployment().properties.templateLink.uri, 'nested/azuredeploy.json')]"

The following example template shows how to use uri, uriComponent, and uriComponentToString.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "uriFormat": "[uri('http://contoso.com/resources/', 'nested/azuredeploy.json')]",
    "uriEncoded": "[uriComponent(variables('uriFormat'))]"
  },
  "resources": [
  ],
  "outputs": {
    "uriOutput": {
      "type": "string",
      "value": "[variables('uriFormat')]"
    },
    "componentOutput": {
      "type": "string",
      "value": "[variables('uriEncoded')]"
    },
    "toStringOutput": {
      "type": "string",
      "value": "[uriComponentToString(variables('uriEncoded'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
uriOutput String http://contoso.com/resources/nested/azuredeploy.json
componentOutput String http%3A%2F%2Fcontoso.com%2Fresources%2Fnested%2Fazuredeploy.json
toStringOutput String http://contoso.com/resources/nested/azuredeploy.json

uriComponent

uricomponent(stringToEncode)

Encodes a URI.

In Bicep, use the uriComponent function.

Parameters

Parameter Required Type Description
stringToEncode Yes string The value to encode.

Return value

A string of the URI encoded value.

Examples

The following example template shows how to use uri, uriComponent, and uriComponentToString.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "uriFormat": "[uri('http://contoso.com/resources/', 'nested/azuredeploy.json')]",
    "uriEncoded": "[uriComponent(variables('uriFormat'))]"
  },
  "resources": [
  ],
  "outputs": {
    "uriOutput": {
      "type": "string",
      "value": "[variables('uriFormat')]"
    },
    "componentOutput": {
      "type": "string",
      "value": "[variables('uriEncoded')]"
    },
    "toStringOutput": {
      "type": "string",
      "value": "[uriComponentToString(variables('uriEncoded'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
uriOutput String http://contoso.com/resources/nested/azuredeploy.json
componentOutput String http%3A%2F%2Fcontoso.com%2Fresources%2Fnested%2Fazuredeploy.json
toStringOutput String http://contoso.com/resources/nested/azuredeploy.json

uriComponentToString

uriComponentToString(uriEncodedString)

Returns a string of a URI encoded value.

In Bicep, use the uriComponentToString function.

Parameters

Parameter Required Type Description
uriEncodedString Yes string The URI encoded value to convert to a string.

Return value

A decoded string of URI encoded value.

Examples

The following example shows how to use uri, uriComponent, and uriComponentToString.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "variables": {
    "uriFormat": "[uri('http://contoso.com/resources/', 'nested/azuredeploy.json')]",
    "uriEncoded": "[uriComponent(variables('uriFormat'))]"
  },
  "resources": [
  ],
  "outputs": {
    "uriOutput": {
      "type": "string",
      "value": "[variables('uriFormat')]"
    },
    "componentOutput": {
      "type": "string",
      "value": "[variables('uriEncoded')]"
    },
    "toStringOutput": {
      "type": "string",
      "value": "[uriComponentToString(variables('uriEncoded'))]"
    }
  }
}

The output from the preceding example with the default values is:

Name Type Value
uriOutput String http://contoso.com/resources/nested/azuredeploy.json
componentOutput String http%3A%2F%2Fcontoso.com%2Fresources%2Fnested%2Fazuredeploy.json
toStringOutput String http://contoso.com/resources/nested/azuredeploy.json

Next steps