|
| 1 | +--- |
| 2 | +title: Template functions - date |
| 3 | +description: Describes the functions to use in an Azure Resource Manager template to work with dates. |
| 4 | +ms.topic: conceptual |
| 5 | +ms.date: 04/06/2020 |
| 6 | +--- |
| 7 | +# String functions for ARM templates |
| 8 | + |
| 9 | +Resource Manager provides the following functions for working with strings in your Azure Resource Manager (ARM) templates: |
| 10 | + |
| 11 | +* [dateTimeAdd](#datetimeadd) |
| 12 | +* [utcNow](#utcnow) |
| 13 | + |
| 14 | +## dateTimeAdd |
| 15 | + |
| 16 | +`dateTimeAdd(base, duration, [format])` |
| 17 | + |
| 18 | +Adds a time duration to a base datetime value. |
| 19 | + |
| 20 | +### Parameters |
| 21 | + |
| 22 | +| Parameter | Required | Type | Description | |
| 23 | +|:--- |:--- |:--- |:--- | |
| 24 | +| base | Yes | string ([ISO 8601 timestamp format](https://en.wikipedia.org/wiki/ISO_8601)) | The starting datetime value for the addition. | |
| 25 | +| duration | Yes | string ([ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations)) | The time value to add to the base. It can be a negative value. | |
| 26 | +| format | No | string | The output format for the date time result. If not provided, the format of the base value is used. Use either [standard format strings](https://docs.microsoft.com/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom format strings](https://docs.microsoft.com/dotnet/standard/base-types/custom-date-and-time-format-strings). | |
| 27 | + |
| 28 | +### Return value |
| 29 | + |
| 30 | +The datetime value that results from adding the duration value to the base value. |
| 31 | + |
| 32 | +### Examples |
| 33 | + |
| 34 | +The following example template shows different ways of adding time values. |
| 35 | + |
| 36 | +```json |
| 37 | +{ |
| 38 | + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", |
| 39 | + "contentVersion": "1.0.0.0", |
| 40 | + "parameters":{ |
| 41 | + "baseTime":{ |
| 42 | + "type":"string", |
| 43 | + "defaultValue": "[utcNow('u')]" |
| 44 | + } |
| 45 | + }, |
| 46 | + "variables": { |
| 47 | + "add3Years": "[dateTimeAdd(parameters('baseTime'), 'P3Y')]", |
| 48 | + "subtract9Days": "[dateTimeAdd(parameters('baseTime'), '-P9D')]", |
| 49 | + "add1Hour": "[dateTimeAdd(parameters('baseTime'), 'PT1H')]" |
| 50 | + }, |
| 51 | + "resources": [], |
| 52 | + "outputs": { |
| 53 | + "add3Years": { |
| 54 | + "value": "[variables('add3Years')]", |
| 55 | + "type": "string" |
| 56 | + }, |
| 57 | + "subtract9Days": { |
| 58 | + "value": "[variables('subtract9Days')]", |
| 59 | + "type": "string" |
| 60 | + }, |
| 61 | + "add1Hour": { |
| 62 | + "value": "[variables('add1Hour')]", |
| 63 | + "type": "string" |
| 64 | + }, |
| 65 | + } |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +When the preceding template is deployed with a base time of `2020-04-07 14:53:14Z`, the output is: |
| 70 | + |
| 71 | +| Name | Type | Value | |
| 72 | +| ---- | ---- | ----- | |
| 73 | +| add3Years | String | 4/7/2023 2:53:14 PM | |
| 74 | +| subtract9Days | String | 3/29/2020 2:53:14 PM | |
| 75 | +| add1Hour | String | 4/7/2020 3:53:14 PM | |
| 76 | + |
| 77 | +## utcNow |
| 78 | + |
| 79 | +`utcNow(format)` |
| 80 | + |
| 81 | +Returns the current (UTC) datetime value in the specified format. If no format is provided, the ISO 8601 (yyyyMMddTHHmmssZ) format is used. **This function can only be used in the default value for a parameter.** |
| 82 | + |
| 83 | +### Parameters |
| 84 | + |
| 85 | +| Parameter | Required | Type | Description | |
| 86 | +|:--- |:--- |:--- |:--- | |
| 87 | +| format |No |string |The URI encoded value to convert to a string. Use either [standard format strings](https://docs.microsoft.com/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom format strings](https://docs.microsoft.com/dotnet/standard/base-types/custom-date-and-time-format-strings). | |
| 88 | + |
| 89 | +### Remarks |
| 90 | + |
| 91 | +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. |
| 92 | + |
| 93 | +If you use the [option to redeploy an earlier successful deployment](rollback-on-error.md), and the earlier deployment includes a parameter that uses utcNow, the parameter isn't reevaluated. Instead, the parameter value from the earlier deployment is automatically reused in the rollback deployment. |
| 94 | + |
| 95 | +Be careful redeploying a template that relies on the utcNow 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. |
| 96 | + |
| 97 | +### Return value |
| 98 | + |
| 99 | +The current UTC datetime value. |
| 100 | + |
| 101 | +### Examples |
| 102 | + |
| 103 | +The following example template shows different formats for the datetime value. |
| 104 | + |
| 105 | +```json |
| 106 | +{ |
| 107 | + "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#", |
| 108 | + "contentVersion": "1.0.0.0", |
| 109 | + "parameters": { |
| 110 | + "utcValue": { |
| 111 | + "type": "string", |
| 112 | + "defaultValue": "[utcNow()]" |
| 113 | + }, |
| 114 | + "utcShortValue": { |
| 115 | + "type": "string", |
| 116 | + "defaultValue": "[utcNow('d')]" |
| 117 | + }, |
| 118 | + "utcCustomValue": { |
| 119 | + "type": "string", |
| 120 | + "defaultValue": "[utcNow('M d')]" |
| 121 | + } |
| 122 | + }, |
| 123 | + "resources": [ |
| 124 | + ], |
| 125 | + "outputs": { |
| 126 | + "utcOutput": { |
| 127 | + "type": "string", |
| 128 | + "value": "[parameters('utcValue')]" |
| 129 | + }, |
| 130 | + "utcShortOutput": { |
| 131 | + "type": "string", |
| 132 | + "value": "[parameters('utcShortValue')]" |
| 133 | + }, |
| 134 | + "utcCustomOutput": { |
| 135 | + "type": "string", |
| 136 | + "value": "[parameters('utcCustomValue')]" |
| 137 | + } |
| 138 | + } |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +The output from the preceding example varies for each deployment but will be similar to: |
| 143 | + |
| 144 | +| Name | Type | Value | |
| 145 | +| ---- | ---- | ----- | |
| 146 | +| utcOutput | string | 20190305T175318Z | |
| 147 | +| utcShortOutput | string | 03/05/2019 | |
| 148 | +| utcCustomOutput | string | 3 5 | |
| 149 | + |
| 150 | +The next example shows how to use a value from the function when setting a tag value. |
| 151 | + |
| 152 | +```json |
| 153 | +{ |
| 154 | + "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#", |
| 155 | + "contentVersion": "1.0.0.0", |
| 156 | + "parameters": { |
| 157 | + "utcShort": { |
| 158 | + "type": "string", |
| 159 | + "defaultValue": "[utcNow('d')]" |
| 160 | + }, |
| 161 | + "rgName": { |
| 162 | + "type": "string" |
| 163 | + } |
| 164 | + }, |
| 165 | + "resources": [ |
| 166 | + { |
| 167 | + "type": "Microsoft.Resources/resourceGroups", |
| 168 | + "apiVersion": "2018-05-01", |
| 169 | + "name": "[parameters('rgName')]", |
| 170 | + "location": "westeurope", |
| 171 | + "tags":{ |
| 172 | + "createdDate": "[parameters('utcShort')]" |
| 173 | + }, |
| 174 | + "properties":{} |
| 175 | + } |
| 176 | + ], |
| 177 | + "outputs": { |
| 178 | + "utcShort": { |
| 179 | + "type": "string", |
| 180 | + "value": "[parameters('utcShort')]" |
| 181 | + } |
| 182 | + } |
| 183 | +} |
| 184 | +``` |
0 commit comments