Skip to content

Commit 916fc0d

Browse files
AnnaMHuffAnnaMHuff
authored
Merge pull request #302539 from mumian/0708-tryget
add tryGet for array
2 parents 976360e + 4a492c7 commit 916fc0d

File tree

4 files changed

+141
-5
lines changed

4 files changed

+141
-5
lines changed

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

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Template functions - arrays
33
description: Describes the functions to use in an Azure Resource Manager template (ARM template) for working with arrays.
44
ms.topic: reference
55
ms.custom: devx-track-arm-template
6-
ms.date: 07/07/2025
6+
ms.date: 07/10/2025
77
---
88

99
# Array functions for ARM templates
@@ -744,6 +744,73 @@ The output from the preceding example with the default values is:
744744
| arrayOutput | Array | ["one", "two"] |
745745
| stringOutput | String | on |
746746

747+
## tryGet
748+
749+
`tryGet(itemToTest, keyOrIndex)`
750+
751+
`tryGet` helps you avoid deployment failures when trying to access a non-existent property or index in an object or array. If the specified key or index does not exist, `tryGet` returns null instead of throwing an error.
752+
753+
In Bicep, use the [safe-dereference](../bicep/operator-safe-dereference.md#safe-dereference) operator.
754+
755+
### Parameters
756+
757+
| Parameter | Required | Type | Description |
758+
|:--- |:--- |:--- |:--- |
759+
| itemToTest |Yes |array, object |An object or array to look into. |
760+
| keyOrIndex |Yes |string, int |A key or index to retrieve from the array or object. A property name for objects or index for arrays.|
761+
762+
### Return value
763+
764+
Returns the value at the key/index if it exists. Returns null if the key/index is missing or out of bounds.
765+
766+
### Example
767+
768+
The following example checks whether an array, object, and string are empty.
769+
770+
```json
771+
{
772+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
773+
"languageVersion": "2.0",
774+
"contentVersion": "1.0.0.0",
775+
"variables": {
776+
"users": {
777+
"name": "John Doe",
778+
"age": 30
779+
},
780+
"colors": [
781+
"red",
782+
"green"
783+
]
784+
},
785+
"resources": [],
786+
"outputs": {
787+
"region": {
788+
"type": "string",
789+
"nullable": true,
790+
"value": "[tryGet(variables('users'), 'region')]"
791+
},
792+
"name": {
793+
"type": "string",
794+
"nullable": true,
795+
"value": "[tryGet(variables('users'), 'name')]"
796+
},
797+
"firstColor": {
798+
"type": "string",
799+
"nullable": true,
800+
"value": "[tryGet(variables('colors'), 0)]"
801+
}
802+
}
803+
}
804+
```
805+
806+
The output from the preceding example is:
807+
808+
| Name | Type | Value |
809+
| ---- | ---- | ----- |
810+
| region | String | (NULL) |
811+
| name | String | John Doe |
812+
| firstColor | String | Red |
813+
747814
## tryIndexFromEnd
748815

749816
`tryndexFromEnd(sourceArray, reverseIndex)`

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

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Template functions - objects
33
description: Describes the functions to use in an Azure Resource Manager template (ARM template) for working with objects.
44
ms.topic: reference
55
ms.custom: devx-track-arm-template
6-
ms.date: 02/12/2025
6+
ms.date: 07/10/2025
77
---
88

99
# Object functions for ARM templates
@@ -540,6 +540,73 @@ The output from the preceding example with the default values is:
540540

541541
**secondOutput** shows the shallow merge doesn't recursively merge these nested objects. Instead, the entire nested object is replaced by the corresponding property from the merging object.
542542

543+
## tryGet
544+
545+
`tryGet(itemToTest, keyOrIndex)`
546+
547+
`tryGet` helps you avoid deployment failures when trying to access a non-existent property or index in an object or array. If the specified key or index doesn't exist, `tryGet` returns null instead of throwing an error.
548+
549+
In Bicep, use the [safe-dereference](../bicep/operator-safe-dereference.md#safe-dereference) operator.
550+
551+
### Parameters
552+
553+
| Parameter | Required | Type | Description |
554+
|:--- |:--- |:--- |:--- |
555+
| itemToTest |Yes |array, object |An object or array to look into. |
556+
| keyOrIndex |Yes |string, int |A key or index to retrieve from the array or object. A property name for objects or index for arrays.|
557+
558+
### Return value
559+
560+
Returns the value at the key/index if it exists. Returns null if the key/index is missing or out of bounds.
561+
562+
### Example
563+
564+
The following example checks whether an array, object, and string are empty.
565+
566+
```json
567+
{
568+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
569+
"languageVersion": "2.0",
570+
"contentVersion": "1.0.0.0",
571+
"variables": {
572+
"users": {
573+
"name": "John Doe",
574+
"age": 30
575+
},
576+
"colors": [
577+
"red",
578+
"green"
579+
]
580+
},
581+
"resources": [],
582+
"outputs": {
583+
"region": {
584+
"type": "string",
585+
"nullable": true,
586+
"value": "[tryGet(variables('users'), 'region')]"
587+
},
588+
"name": {
589+
"type": "string",
590+
"nullable": true,
591+
"value": "[tryGet(variables('users'), 'name')]"
592+
},
593+
"firstColor": {
594+
"type": "string",
595+
"nullable": true,
596+
"value": "[tryGet(variables('colors'), 0)]"
597+
}
598+
}
599+
}
600+
```
601+
602+
The output from the preceding example is:
603+
604+
| Name | Type | Value |
605+
| ---- | ---- | ----- |
606+
| region | String | (NULL) |
607+
| name | String | John Doe |
608+
| firstColor | String | Red |
609+
543610
## union
544611

545612
`union(arg1, arg2, arg3, ...)`

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Template functions
33
description: Describes the functions to use in an Azure Resource Manager template (ARM template) to retrieve values, work with strings and numerics, and retrieve deployment information.
44
ms.topic: reference
55
ms.custom: devx-track-arm-template
6-
ms.date: 07/07/2025
6+
ms.date: 07/10/2025
77
---
88

99
# ARM template functions
@@ -64,6 +64,7 @@ Resource Manager provides several functions for working with arrays.
6464
* [range](template-functions-array.md#range)
6565
* [skip](template-functions-array.md#skip)
6666
* [take](template-functions-array.md#take)
67+
* [tryGet](template-functions-array.md#tryget)
6768
* [tryIndexFromEnd](template-functions-array.md#tryindexfromend)
6869
* [union](template-functions-array.md#union)
6970

@@ -229,6 +230,7 @@ Resource Manager provides several functions for working with objects.
229230
* [null](template-functions-object.md#null)
230231
* [objectKeys](template-functions-object.md#objectkeys)
231232
* [shallowMerge](template-functions-object.md#shallowmerge)
233+
* [tryGet](template-functions-object.md#tryget)
232234
* [union](template-functions-object.md#union)
233235

234236
For Bicep files, use the [object](../bicep/bicep-functions-object.md) functions.

‎articles/azure-resource-manager/templates/toc.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -470,7 +470,7 @@ items:
470470
- name: All functions
471471
href: template-functions.md
472472
- name: Array functions
473-
displayName: array,concat,contains,createArray,empty,first,indexFromEnd,indexOf,intersection,last,lastIndexOf,length,max,min,range,skip,take,tryIndexFromEdn,union
473+
displayName: array,concat,contains,createArray,empty,first,indexFromEnd,indexOf,intersection,last,lastIndexOf,length,max,min,range,skip,take,tryIndexFromEnd,tryGet,union
474474
href: template-functions-array.md
475475
- name: CIDR functions
476476
displayName: parseCidr,cidrSubnet,cidrHost
@@ -494,7 +494,7 @@ items:
494494
displayName: add,copyIndex,div,float,int,max,min,mod,mul,sub
495495
href: template-functions-numeric.md
496496
- name: Object functions
497-
displayName: contains,createObject,empty,intersection,items,json,length,null,objectKeys,shallowMerge,union
497+
displayName: contains,createObject,empty,intersection,items,json,length,null,objectKeys,shallowMerge,tryGet,union
498498
href: template-functions-object.md
499499
- name: Resource functions
500500
displayName: extensionResourceId,listAccountSas,listKeys,listSecrets,list*,pickZones,providers,reference,references,resourceId,subscriptionResourceId,managementGroupResourceId,tenantResourceId

0 commit comments

Comments
 (0)