Skip to content

Commit b377863

Browse files
v-albemiv-albemi
authored
Merge pull request #110558 from tfitzmac/0406datetime
add dateTimeAdd
2 parents eec9231 + 70eb8a1 commit b377863

File tree

5 files changed

+251
-115
lines changed

5 files changed

+251
-115
lines changed

‎articles/azure-resource-manager/templates/deployment-script-template.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -308,7 +308,7 @@ The life cycle of these resources is controlled by the following properties in t
308308

309309
Deployment script execution is an idempotent operation. If none of the deploymentScripts resource properties (including the inline script) is changed, the script will not be executed when you redeploy the template. The deployment script service compares the resource names in the template with the existing resources in the same resource group. There are two options if you want to execute the same deployment script multiple times:
310310

311-
- Change the name of your deploymentScripts resource. For example, use the [utcNow](./template-functions-string.md#utcnow) template function as the resource name or as a part of the resource name. Changing the resource name creates a new deploymentScripts resource. It is good for keeping a history of script execution.
311+
- Change the name of your deploymentScripts resource. For example, use the [utcNow](./template-functions-date.md#utcnow) template function as the resource name or as a part of the resource name. Changing the resource name creates a new deploymentScripts resource. It is good for keeping a history of script execution.
312312

313313
> [!NOTE]
314314
> The utcNow function can only be used in the default value for a parameter.

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

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
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+
# Date functions for ARM templates
8+
9+
Resource Manager provides the following functions for working with dates 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 | The starting datetime value for the addition. Use [ISO 8601 timestamp format](https://en.wikipedia.org/wiki/ISO_8601). |
25+
| 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). |
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+
The next example template shows how to set the start time for an Automation schedule.
78+
79+
```json
80+
{
81+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
82+
"contentVersion": "1.0.0.0",
83+
"parameters": {
84+
"omsAutomationAccountName": {
85+
"type": "string",
86+
"defaultValue": "demoAutomation",
87+
"metadata": {
88+
"description": "Use an existing Automation account."
89+
}
90+
},
91+
"scheduleName": {
92+
"type": "string",
93+
"defaultValue": "demoSchedule1",
94+
"metadata": {
95+
"description": "Name of the new schedule."
96+
}
97+
},
98+
"baseTime":{
99+
"type":"string",
100+
"defaultValue": "[utcNow('u')]",
101+
"metadata": {
102+
"description": "Schedule will start one hour from this time."
103+
}
104+
}
105+
},
106+
"variables": {
107+
"startTime": "[dateTimeAdd(parameters('baseTime'), 'PT1H')]"
108+
},
109+
"resources": [
110+
{
111+
"name": "[concat(parameters('omsAutomationAccountName'), '/', parameters('scheduleName'))]",
112+
"type": "microsoft.automation/automationAccounts/schedules",
113+
"apiVersion": "2015-10-31",
114+
"location": "eastus2",
115+
"tags": {
116+
},
117+
"properties": {
118+
"description": "Demo Scheduler",
119+
"startTime": "[variables('startTime')]",
120+
"isEnabled": "true",
121+
"interval": 1,
122+
"frequency": "hour"
123+
}
124+
}
125+
],
126+
"outputs": {
127+
}
128+
}
129+
```
130+
131+
## utcNow
132+
133+
`utcNow(format)`
134+
135+
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.**
136+
137+
### Parameters
138+
139+
| Parameter | Required | Type | Description |
140+
|:--- |:--- |:--- |:--- |
141+
| 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). |
142+
143+
### Remarks
144+
145+
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.
146+
147+
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.
148+
149+
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.
150+
151+
### Return value
152+
153+
The current UTC datetime value.
154+
155+
### Examples
156+
157+
The following example template shows different formats for the datetime value.
158+
159+
```json
160+
{
161+
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
162+
"contentVersion": "1.0.0.0",
163+
"parameters": {
164+
"utcValue": {
165+
"type": "string",
166+
"defaultValue": "[utcNow()]"
167+
},
168+
"utcShortValue": {
169+
"type": "string",
170+
"defaultValue": "[utcNow('d')]"
171+
},
172+
"utcCustomValue": {
173+
"type": "string",
174+
"defaultValue": "[utcNow('M d')]"
175+
}
176+
},
177+
"resources": [
178+
],
179+
"outputs": {
180+
"utcOutput": {
181+
"type": "string",
182+
"value": "[parameters('utcValue')]"
183+
},
184+
"utcShortOutput": {
185+
"type": "string",
186+
"value": "[parameters('utcShortValue')]"
187+
},
188+
"utcCustomOutput": {
189+
"type": "string",
190+
"value": "[parameters('utcCustomValue')]"
191+
}
192+
}
193+
}
194+
```
195+
196+
The output from the preceding example varies for each deployment but will be similar to:
197+
198+
| Name | Type | Value |
199+
| ---- | ---- | ----- |
200+
| utcOutput | string | 20190305T175318Z |
201+
| utcShortOutput | string | 03/05/2019 |
202+
| utcCustomOutput | string | 3 5 |
203+
204+
The next example shows how to use a value from the function when setting a tag value.
205+
206+
```json
207+
{
208+
"$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
209+
"contentVersion": "1.0.0.0",
210+
"parameters": {
211+
"utcShort": {
212+
"type": "string",
213+
"defaultValue": "[utcNow('d')]"
214+
},
215+
"rgName": {
216+
"type": "string"
217+
}
218+
},
219+
"resources": [
220+
{
221+
"type": "Microsoft.Resources/resourceGroups",
222+
"apiVersion": "2018-05-01",
223+
"name": "[parameters('rgName')]",
224+
"location": "westeurope",
225+
"tags":{
226+
"createdDate": "[parameters('utcShort')]"
227+
},
228+
"properties":{}
229+
}
230+
],
231+
"outputs": {
232+
"utcShort": {
233+
"type": "string",
234+
"value": "[parameters('utcShort')]"
235+
}
236+
}
237+
}
238+
```

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

Lines changed: 2 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Template functions - string
33
description: Describes the functions to use in an Azure Resource Manager template to work with strings.
44
ms.topic: conceptual
5-
ms.date: 07/31/2019
5+
ms.date: 04/06/2020
66
---
77
# String functions for ARM templates
88

@@ -40,7 +40,6 @@ Resource Manager provides the following functions for working with strings in yo
4040
* [uri](#uri)
4141
* [uriComponent](#uricomponent)
4242
* [uriComponentToString](#uricomponenttostring)
43-
* [utcNow](#utcnow)
4443

4544
## base64
4645

@@ -1870,7 +1869,7 @@ The following example shows how to create a unique name for a storage account ba
18701869
...
18711870
```
18721871

1873-
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](#utcnow) function with uniqueString. You could use this approach in a test environment. For an example, see [utcNow](#utcnow).
1872+
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](template-functions-date.md#utcnow) function with uniqueString. You could use this approach in a test environment. For an example, see [utcNow](template-functions-date.md#utcnow).
18741873

18751874
### Return value
18761875

@@ -2095,115 +2094,6 @@ The output from the preceding example with the default values is:
20952094
| componentOutput | String | `http%3A%2F%2Fcontoso.com%2Fresources%2Fnested%2Fazuredeploy.json` |
20962095
| toStringOutput | String | `http://contoso.com/resources/nested/azuredeploy.json` |
20972096

2098-
## utcNow
2099-
2100-
`utcNow(format)`
2101-
2102-
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.**
2103-
2104-
### Parameters
2105-
2106-
| Parameter | Required | Type | Description |
2107-
|:--- |:--- |:--- |:--- |
2108-
| 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). |
2109-
2110-
### Remarks
2111-
2112-
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.
2113-
2114-
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.
2115-
2116-
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.
2117-
2118-
### Return value
2119-
2120-
The current UTC datetime value.
2121-
2122-
### Examples
2123-
2124-
The following example template shows different formats for the datetime value.
2125-
2126-
```json
2127-
{
2128-
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
2129-
"contentVersion": "1.0.0.0",
2130-
"parameters": {
2131-
"utcValue": {
2132-
"type": "string",
2133-
"defaultValue": "[utcNow()]"
2134-
},
2135-
"utcShortValue": {
2136-
"type": "string",
2137-
"defaultValue": "[utcNow('d')]"
2138-
},
2139-
"utcCustomValue": {
2140-
"type": "string",
2141-
"defaultValue": "[utcNow('M d')]"
2142-
}
2143-
},
2144-
"resources": [
2145-
],
2146-
"outputs": {
2147-
"utcOutput": {
2148-
"type": "string",
2149-
"value": "[parameters('utcValue')]"
2150-
},
2151-
"utcShortOutput": {
2152-
"type": "string",
2153-
"value": "[parameters('utcShortValue')]"
2154-
},
2155-
"utcCustomOutput": {
2156-
"type": "string",
2157-
"value": "[parameters('utcCustomValue')]"
2158-
}
2159-
}
2160-
}
2161-
```
2162-
2163-
The output from the preceding example varies for each deployment but will be similar to:
2164-
2165-
| Name | Type | Value |
2166-
| ---- | ---- | ----- |
2167-
| utcOutput | string | 20190305T175318Z |
2168-
| utcShortOutput | string | 03/05/2019 |
2169-
| utcCustomOutput | string | 3 5 |
2170-
2171-
The next example shows how to use a value from the function when setting a tag value.
2172-
2173-
```json
2174-
{
2175-
"$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
2176-
"contentVersion": "1.0.0.0",
2177-
"parameters": {
2178-
"utcShort": {
2179-
"type": "string",
2180-
"defaultValue": "[utcNow('d')]"
2181-
},
2182-
"rgName": {
2183-
"type": "string"
2184-
}
2185-
},
2186-
"resources": [
2187-
{
2188-
"type": "Microsoft.Resources/resourceGroups",
2189-
"apiVersion": "2018-05-01",
2190-
"name": "[parameters('rgName')]",
2191-
"location": "westeurope",
2192-
"tags":{
2193-
"createdDate": "[parameters('utcShort')]"
2194-
},
2195-
"properties":{}
2196-
}
2197-
],
2198-
"outputs": {
2199-
"utcShort": {
2200-
"type": "string",
2201-
"value": "[parameters('utcShort')]"
2202-
}
2203-
}
2204-
}
2205-
```
2206-
22072097
## Next steps
22082098
* For a description of the sections in an Azure Resource Manager template, see [Authoring Azure Resource Manager templates](template-syntax.md).
22092099
* To merge multiple templates, see [Using linked templates with Azure Resource Manager](linked-templates.md).

0 commit comments

Comments
 (0)