Skip to content

Commit e0960e7

Browse files
AnnaMHuffAnnaMHuff
authored
Merge pull request #303746 from LiSeda/LS-arm4
LS_ARM_batch 4
2 parents e4e1371 + 7b23d2d commit e0960e7

File tree

4 files changed

+565
-108
lines changed

4 files changed

+565
-108
lines changed

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

Lines changed: 169 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -3,31 +3,31 @@ title: Template functions - date
33
description: Describes the functions to use in an Azure Resource Manager template (ARM template) to work with dates.
44
ms.topic: reference
55
ms.custom: devx-track-arm-template
6-
ms.date: 02/12/2025
6+
ms.date: 08/08/2025
77
---
88

99
# Date functions for ARM templates
1010

1111
This article describes the functions for working with dates in your Azure Resource Manager template (ARM template).
1212

1313
> [!TIP]
14-
> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [date](../bicep/bicep-functions-date.md) functions.
14+
> [Bicep](../bicep/overview.md) is recommended because it offers the same capabilities as ARM templates, and the syntax is easier to use. To learn more, see [`date`](../bicep/bicep-functions-date.md) functions.
1515
1616
## dateTimeAdd
1717

1818
`dateTimeAdd(base, duration, [format])`
1919

2020
Adds a time duration to a base value. ISO 8601 format is expected.
2121

22-
In Bicep, use the [dateTimeAdd](../bicep/bicep-functions-date.md#datetimeadd) function.
22+
In Bicep, use the [`dateTimeAdd`](../bicep/bicep-functions-date.md#datetimeadd) function.
2323

2424
### Parameters
2525

2626
| Parameter | Required | Type | Description |
2727
|:--- |:--- |:--- |:--- |
2828
| base | Yes | string | The starting datetime value for the addition. Use [ISO 8601 timestamp format](https://en.wikipedia.org/wiki/ISO_8601). |
2929
| duration | Yes | string | The time value to add to the base. It can be a negative value. Use [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations). |
30-
| 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](/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). |
30+
| format | No | string | The output format for the datetime result. If not provided, the format of the base value is used. Use either [standard-format](/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom-format](/dotnet/standard/base-types/custom-date-and-time-format-strings) strings. |
3131

3232
### Return value
3333

@@ -67,9 +67,40 @@ In the preceding example, considering 2023 as a non-leap year, the outcome of ad
6767

6868
### Examples
6969

70-
The following example template shows different ways of adding time values.
70+
The following example template shows different ways of adding time values:
7171

72-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/date/datetimeadd.json":::
72+
```json
73+
{
74+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
75+
"contentVersion": "1.0.0.0",
76+
"parameters": {
77+
"baseTime": {
78+
"type": "string",
79+
"defaultValue": "[utcNow('u')]"
80+
}
81+
},
82+
"variables": {
83+
"add3Years": "[dateTimeAdd(parameters('baseTime'), 'P3Y')]",
84+
"subtract9Days": "[dateTimeAdd(parameters('baseTime'), '-P9D')]",
85+
"add1Hour": "[dateTimeAdd(parameters('baseTime'), 'PT1H')]"
86+
},
87+
"resources": [],
88+
"outputs": {
89+
"add3YearsOutput": {
90+
"value": "[variables('add3Years')]",
91+
"type": "string"
92+
},
93+
"subtract9DaysOutput": {
94+
"value": "[variables('subtract9Days')]",
95+
"type": "string"
96+
},
97+
"add1HourOutput": {
98+
"value": "[variables('add1Hour')]",
99+
"type": "string"
100+
}
101+
}
102+
}
103+
```
73104

74105
When the preceding template is deployed with a base time of `2020-04-07 14:53:14Z`, the output is:
75106

@@ -79,17 +110,65 @@ When the preceding template is deployed with a base time of `2020-04-07 14:53:14
79110
| subtract9DaysOutput | String | 3/29/2020 2:53:14 PM |
80111
| add1HourOutput | String | 4/7/2020 3:53:14 PM |
81112

82-
The next example template shows how to set the start time for an Automation schedule.
113+
The next example template shows how to set the start time for an automation schedule:
83114

84-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/date/datetimeadd-automation.json":::
115+
```json
116+
{
117+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
118+
"contentVersion": "1.0.0.0",
119+
"parameters": {
120+
"omsAutomationAccountName": {
121+
"type": "string",
122+
"defaultValue": "demoAutomation",
123+
"metadata": {
124+
"description": "Use an existing Automation account."
125+
}
126+
},
127+
"scheduleName": {
128+
"type": "string",
129+
"defaultValue": "demoSchedule1",
130+
"metadata": {
131+
"description": "Name of the new schedule."
132+
}
133+
},
134+
"baseTime": {
135+
"type": "string",
136+
"defaultValue": "[utcNow('u')]",
137+
"metadata": {
138+
"description": "Schedule will start one hour from this time."
139+
}
140+
}
141+
},
142+
"variables": {
143+
"startTime": "[dateTimeAdd(parameters('baseTime'), 'PT1H')]"
144+
},
145+
"resources": [
146+
...
147+
{
148+
"type": "Microsoft.Automation/automationAccounts/schedules",
149+
"apiVersion": "2022-08-08",
150+
"name": "[concat(parameters('omsAutomationAccountName'), '/', parameters('scheduleName'))]",
151+
152+
"properties": {
153+
"description": "Demo Scheduler",
154+
"startTime": "[variables('startTime')]",
155+
"interval": 1,
156+
"frequency": "Hour"
157+
}
158+
}
159+
],
160+
"outputs": {
161+
}
162+
}
163+
```
85164

86165
## dateTimeFromEpoch
87166

88167
`dateTimeFromEpoch(epochTime)`
89168

90169
Converts an epoch time integer value to an ISO 8601 datetime.
91170

92-
In Bicep, use the [dateTimeFromEpoch](../bicep/bicep-functions-date.md#datetimefromepoch) function.
171+
In Bicep, use the [`dateTimeFromEpoch`](../bicep/bicep-functions-date.md#datetimefromepoch) function.
93172

94173
### Parameters
95174

@@ -103,7 +182,7 @@ An ISO 8601 datetime string.
103182

104183
### Example
105184

106-
The following example shows output values for the epoch time functions.
185+
The following example shows output values for the `epoch` time functions:
107186

108187
```json
109188
{
@@ -145,7 +224,7 @@ The output is:
145224

146225
Converts an ISO 8601 datetime string to an epoch time integer value.
147226

148-
In Bicep, use the [dateTimeToEpoch](../bicep/bicep-functions-date.md#datetimetoepoch) function.
227+
In Bicep, use the [`dateTimeToEpoch`](../bicep/bicep-functions-date.md#datetimetoepoch) function.
149228

150229
### Parameters
151230

@@ -159,7 +238,7 @@ An integer that represents the number of seconds from midnight on January 1, 197
159238

160239
### Examples
161240

162-
The following example shows output values for the epoch time functions.
241+
The following example shows output values for the `epoch` time functions:
163242

164243
```json
165244
{
@@ -195,41 +274,76 @@ The output is:
195274
| datetimeValue | String | 2023-05-02T15:16:13Z |
196275
| epochValue | Int | 1683040573 |
197276

198-
The next example uses the epoch time value to set the expiration for a key in a key vault.
277+
The next example uses the epoch time value to set the expiration for a key in a key vault:
199278

200-
:::code language="json" source="~/quickstart-templates/quickstarts/microsoft.storage/storage-blob-encryption-with-cmk/azuredeploy.json" highlight="54,104":::
279+
:::code language="json" source="~/quickstart-templates/quickstarts/microsoft.storage/storage-blob-encryption-with-cmk/azuredeploy.json":::
201280

202281
## utcNow
203282

204283
`utcNow(format)`
205284

206285
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.**
207286

208-
In Bicep, use the [utcNow](../bicep/bicep-functions-date.md#utcnow) function.
287+
In Bicep, use the [`utcNow`](../bicep/bicep-functions-date.md#utcnow) function.
209288

210289
### Parameters
211290

212291
| Parameter | Required | Type | Description |
213292
|:--- |:--- |:--- |:--- |
214-
| format |No |string |The URI encoded value to convert to a string. Use either [standard format strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). |
293+
| format |No |string |The URI encoded value to convert to a string. Use either [standard-format](/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom-format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). |
215294

216295
### Remarks
217296

218297
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.
219298

220-
If you use the [option to rollback on error](rollback-on-error.md) to an earlier successful deployment, 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.
299+
If you use the [option to rollback on error](rollback-on-error.md) to an earlier successful deployment when 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.
221300

222301
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.
223302

224303
### Return value
225304

226-
The current UTC datetime value.
305+
The current UTC **datetime** value.
227306

228307
### Examples
229308

230-
The following example template shows different formats for the datetime value.
309+
The following example template shows different formats for the datetime value:
231310

232-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/date/utcnow.json":::
311+
```json
312+
{
313+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
314+
"contentVersion": "1.0.0.0",
315+
"parameters": {
316+
"utcValue": {
317+
"type": "string",
318+
"defaultValue": "[utcNow()]"
319+
},
320+
"utcShortValue": {
321+
"type": "string",
322+
"defaultValue": "[utcNow('d')]"
323+
},
324+
"utcCustomValue": {
325+
"type": "string",
326+
"defaultValue": "[utcNow('M d')]"
327+
}
328+
},
329+
"resources": [
330+
],
331+
"outputs": {
332+
"utcOutput": {
333+
"type": "string",
334+
"value": "[parameters('utcValue')]"
335+
},
336+
"utcShortOutput": {
337+
"type": "string",
338+
"value": "[parameters('utcShortValue')]"
339+
},
340+
"utcCustomOutput": {
341+
"type": "string",
342+
"value": "[parameters('utcCustomValue')]"
343+
}
344+
}
345+
}
346+
```
233347

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

@@ -239,10 +353,42 @@ The output from the preceding example varies for each deployment but will be sim
239353
| utcShortOutput | string | 03/05/2019 |
240354
| utcCustomOutput | string | 3 5 |
241355

242-
The next example shows how to use a value from the function when setting a tag value.
356+
The next example shows how to use a value from the function when setting a tag value:
243357

244-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/functions/date/utcnow-tag.json":::
358+
```json
359+
{
360+
"$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
361+
"contentVersion": "1.0.0.0",
362+
"parameters": {
363+
"utcShort": {
364+
"type": "string",
365+
"defaultValue": "[utcNow('d')]"
366+
},
367+
"rgName": {
368+
"type": "string"
369+
}
370+
},
371+
"resources": [
372+
{
373+
"type": "Microsoft.Resources/resourceGroups",
374+
"apiVersion": "2021-04-01",
375+
"name": "[parameters('rgName')]",
376+
"location": "westeurope",
377+
"tags": {
378+
"createdDate": "[parameters('utcShort')]"
379+
},
380+
"properties": {}
381+
}
382+
],
383+
"outputs": {
384+
"utcShortOutput": {
385+
"type": "string",
386+
"value": "[parameters('utcShort')]"
387+
}
388+
}
389+
}
390+
```
245391

246392
## Next steps
247393

248-
* For a description of the sections in an ARM template, see [Understand the structure and syntax of ARM templates](./syntax.md).
394+
To learn more about the sections in an ARM template, see [the structure and syntax of ARM templates](./syntax.md).

0 commit comments

Comments
 (0)