Test-AzureResourceGroupTemplate
Test-AzureResourceGroupTemplate
Detects errors in a resource group template or template parameters
Syntax
Parameter Set: Deployment via template file without parameters
Test-AzureResourceGroupTemplate -ResourceGroupName <String> -TemplateFile <String> [-StorageAccountName <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]
Parameter Set: Deployment via Gallery and template parameters file
Test-AzureResourceGroupTemplate -GalleryTemplateIdentity <String> -ResourceGroupName <String> -TemplateParameterFile <String> [-TemplateVersion <String> ] [ <CommonParameters>]
Parameter Set: Deployment via Gallery and template parameters object
Test-AzureResourceGroupTemplate -GalleryTemplateIdentity <String> -ResourceGroupName <String> -TemplateParameterObject <Hashtable> [-TemplateVersion <String> ] [ <CommonParameters>]
Parameter Set: Deployment via Gallery without parameters
Test-AzureResourceGroupTemplate -GalleryTemplateIdentity <String> -ResourceGroupName <String> [-TemplateVersion <String> ] [ <CommonParameters>]
Parameter Set: Deployment via template file and template parameters file
Test-AzureResourceGroupTemplate -ResourceGroupName <String> -TemplateFile <String> -TemplateParameterFile <String> [-StorageAccountName <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]
Parameter Set: Deployment via template file and template parameters object
Test-AzureResourceGroupTemplate -ResourceGroupName <String> -TemplateFile <String> -TemplateParameterObject <Hashtable> [-StorageAccountName <String> ] [-TemplateVersion <String> ] [ <CommonParameters>]
Parameter Set: Deployment via template uri and template parameters file
Test-AzureResourceGroupTemplate -ResourceGroupName <String> -TemplateParameterFile <String> -TemplateUri <String> [-TemplateVersion <String> ] [ <CommonParameters>]
Parameter Set: Deployment via template uri and template parameters object
Test-AzureResourceGroupTemplate -ResourceGroupName <String> -TemplateParameterObject <Hashtable> -TemplateUri <String> [-TemplateVersion <String> ] [ <CommonParameters>]
Parameter Set: Deployment via template uri without parameters
Test-AzureResourceGroupTemplate -ResourceGroupName <String> -TemplateUri <String> [-TemplateVersion <String> ] [ <CommonParameters>]
Detailed Description
The Test-AzureResourceGroupTemplate cmdlet verifies the validity of a resource group template, its parameters, and parameter values. It returns errors that it finds. Otherwise, it does not return any output.
To specify a template, use the GalleryTemplateIdentity or TemplateFile parameters.
To specify the template parameter values, use the TemplateParameterFile or TemplateParameterObject parameters, or use the template parameters that are added to the command dynamically when you specify the template. To get the parameters, just type a minus sign (-) to indicate a parameter name and press the TAB key to trigger tab-completion. If you miss a required parameter, the cmdlet prompts you for the value.
A resource group template is a JSON-based model of a resource group for a complex cloud-based service, such as a web portal. You can use a resource group template to create a resource group or resource group deployment. The template includes parameter (placeholders) for configurable property values, likes names and sizes. You can find many templates in the Azure template gallery (Get-AzureResourceGroupGalleryTemplate) and you can create your own templates.
Parameters
-GalleryTemplateIdentity<String>
Specifies the identity of the gallery template to test. Enter an Identity value not a file name. Wildcards are not permitted.
To get the identity of a gallery template, use the Get-AzureResourceGroupGalleryTemplate cmdlet. To test a gallery template that is saved as a JSON file on disk, use the TemplateFile parameter.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-ResourceGroupName<String>
Specify the name of the resource group. This parameter is mandatory. Wildcards are not permitted.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-StorageAccountName<String>
Specifies the name of a storage account in the subscription. Test-AzureResourceGroupGalleryTemplate saves the contents of local template files in the storage account. This parameter is optional, but a storage account is required when you use the TemplateFile parameter.
The default value is the current storage account in the subscription. If you do not specify a storage account and the subscription does not have a storage account that it designated as "current," the command fails.
To create a storage account, use the Switch-AzureMode cmdlet to switch to the Azure module, and then use the New-AzureStorageAccount cmdlet. To make the a storage account the "current storage account" for the subscription, use the CurrentStorageAccountName parameter of the Set-AzureSubscription cmdlet.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-TemplateFile<String>
Specifies the path and file name of a JSON template file on disk. This can be a custom template or a gallery template that is saved to disk as a JSON file, such as by using the Save-AzureResourceGroupGalleryTemplate cmdlet.
To use this parameter, the subscription must include a storage account where the cmdlet can save the template. By default, this cmdlet uses the current storage account in the subscription, but you can use the StorageAccountName parameter to specify an alternate storage account. If you do not specify a storage account and the subscription does not have a storage account that is designated as "current," the command fails.
To create a storage account, use the Switch-AzureMode cmdlet to switch to the Azure module, and then use the New-AzureStorageAccount cmdlet. To make the a storage account the "current storage account" for the subscription, use the CurrentStorageAccountName parameter of the Set-AzureSubscription cmdlet.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-TemplateParameterFile<String>
Specifies the path and name of a JSON file of template parameter names and values. You must specify values for the template parameters, but you can use this parameter, the TemplateParameterObject parameter, or use the parameters that are added to the command dynamically when you specify the template.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-TemplateParameterObject<Hashtable>
Specifies a hash table of template parameter names and values. The parameters and values are case-sensitive. You must specify values for the template parameters, but you can use this parameter, the TemplateParameterFile parameter, or use the parameters that are added to the command dynamically when you specify the template.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-TemplateUri<String>
Specifies the URI of a JSON template file. This file can be a custom template or a gallery template that is saved as a JSON file, such as by using the Save-AzureResourceGroupGalleryTemplate cmdlet.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
-TemplateVersion<String>
Specifies a particular version of the gallery or custom template. Enter the API version number, such as "2014-04-01-preview". This parameter is optional. If you specify this parameter, Test-AzureResourceGroupGalleryTemplate verifies that the specified template has the matching version and fails if it does not.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByPropertyName) |
Accept Wildcard Characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).
Inputs
The input type is the type of the objects that you can pipe to the cmdlet.
None
You can pipe input to this cmdlet by property name, but not by value.
Outputs
The output type is the type of the objects that the cmdlet emits.
Microsoft.Azure.Commands.ResourceManager.Models.PSResourceManagerError
This cmdlet returns a PSResourceManagerError object for each error that it finds. If it does not find an error, it does not return any output.
Notes
- The Test-AzureResourceGroupGalleryTemplate cmdlet is included in the Azure Resource Manager module beginning in module version 0.8.0.
Examples
Example 1: Test a custom template file
This command tests a custom template file, CustomHostingPlan.json, and a template parameter file, HostingPlanParms.json. Because the cmdlet does not find any errors, it does not return any output.
PS C:\> Test-AzureResourceGroupTemplate -ResourceGroupName ContosoLabsRG -TemplateFile $home\Documents\Azure\Templates\CustomHostingPlan.json -TemplateParameterFile $home\Documents\Azure\Templates\HostingPlanParms.json
PS C:>
Example 2: Test a parameter object for a gallery template
This command tests gallery template and a hash table of parameter names and values. The command uses the GalleryTemplateIdentity parameter to specify the identity of the gallery template. It uses the TemplateParameterObject cmdlet to specify the template parameters and their values.
In this case, the template parameter hash table is missing the siteLocation parameter. The cmdlet recognizes the omission and prompts for a value. However, the cmdlet still returns an error, because the subscriptionId parameter in hash table is misspelled as "subscriptionID".
In the second command, the errors are corrected, and the cmdlet does not return any output.
PS C:\> Test-AzureResourceGroupTemplate -ResourceGroupName ContosoLabsRG -GalleryTemplateIdentity Microsoft.WebSite.0.1.0-preview1 -TemplateParameterObject @{siteName = "ContosoSite";hostingPlanName="ContosoHosting";siteMode="Limited";computeMode="Shared";subscriptionID='9b14a38b-4b93-4554-8bb0-3cefb47a4e1f';resourceGroup='ContosoLabsRG'}
cmdlet Test-AzureResourceGroupTemplate at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
siteLocation:
"South Central US"
Code : InvalidTemplate
Message : Deployment template validation failed: 'The template parameters 'subscriptionID' are not valid; they are not present in the original template and can therefore not be provided at deployment time. The only supported
parameters for this template are 'siteName, hostingPlanName, siteMode, computeMode, siteLocation, subscriptionId, resourceGroup'.'.a
PS C:\>Test-AzureResourceGroupTemplate -ResourceGroupName ContosoLabsRG -GalleryTemplateIdentity Microsoft.WebSite.0
.1.0-preview1 -TemplateParameterObject @{siteName = "ContosoSite";hostingPlanName="ContosoHosting";siteMode="Limited";co
mputeMode="Shared";subscriptionId='9b14a38b-4b93-4554-8bb0-3cefb47a4e1f';resourceGroup='ContosoLabsRG';siteLocation='South Central US'}
Example 3: Test a template with dynamic parameter values
This command uses the Test-AzureResourceGroupTemplate cmdlet to test a custom template. Instead of providing the template parameter names, we used the feature that adds the template parameters to command dynamically.
To use the dynamic parameters, type a minus sign (-) to indicate a parameter name and press the TAB key. The tab-completion feature supplies parameter name. To cycle through all of the parameter names, press the TAB key repeatedly. In this case, we used the dynamic parameters to specify all of the parameter names at the command line.
In this case, even though the template parameter names and values are correct, the Parameters section in the custom template is missing the hostingPlan parameter that is specified in the Resource section of the template. The cmdlet detects and reports this error.
PS C:\> Test-AzureResourceGroupTemplate -ResourceGroupName ContosoLabsRG -TemplateFile C:\Users\juneb\Documents\Azure\Templates\NewHostingPlan.json -siteName ContosoDev -siteMode Limited -computeMode Shared -siteLocation 'South Central US' -sku Free
Code : InvalidTemplate
Message : Deployment template validation failed: 'The template parameter 'hostingPlanName' is not valid.'.