Edit

New-AzResourceGroupDeploymentWhatIf

Preview the changes an ARM or Bicep deployment would make to a resource group without applying them.

Syntax

Default (Default)

New-AzResourceGroupDeploymentWhatIf
    -ResourceGroupName <string>
    -Name <string>
    [-TemplateUri <string>]
    [-TemplateFile <string>]
    [-TemplateSpecId <string>]
    [-QueryString <string>]
    [-ParametersUri <string>]
    [-ParametersFile <string>]
    [-Mode <string>]
    [-Parameter <string[]>]
    [-ValidationLevel <string>]
    [-ResultFormat <string>]
    [-SubscriptionId <string>]
    [<CommonParameters>]

Description

Runs an ARM/Bicep what-if operation against an existing resource group and returns the set of resource changes the deployment would produce — additions, modifications, deletions, and no-ops — without creating or modifying any resources. The template is supplied either inline (-TemplateFile), via URL (-TemplateUri), or by referencing a template spec (-TemplateSpecId). Template parameters can be supplied via file, URI, query string, or as Name=Value pairs through -Parameter. Use -ResultFormat ResourceIdOnly for a compact summary, or -ResultFormat FullResourcePayloads (default) to include the full predicted resource bodies.

Examples

Preview a Bicep deployment before applying it

Run a what-if for main.bicep with parameter file main.parameters.json as deployment infra-prod-2026-06-18 against resource group myrg.

New-AzResourceGroupDeploymentWhatIf -ResourceGroupName myrg -Name infra-prod-2026-06-18 -TemplateFile ./main.bicep -ParametersFile ./main.parameters.json -Mode Incremental

Parameters

-Mode

Deployment mode used to evaluate the change set. Use Incremental (default) to add and update resources, or Complete to also report resources in the resource group that aren't declared in the template.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Name

The name of the deployment. Used to track and reference the what-if operation in deployment history.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Parameter

Template parameters supplied as inline Name=Value pairs. Use this when you don't have a parameters file. Repeat the flag or pass an array for multiple values.

Parameter properties

Type:

String[]

Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ParametersFile

Path to a local ARM/Bicep parameters file (*.parameters.json).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ParametersUri

URI of a remote ARM/Bicep parameters file (for example, a blob URL).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-QueryString

Optional SAS or query string appended to -TemplateUri / -ParametersUri when those URIs require authentication.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ResourceGroupName

The name of the resource group to run the what-if against. The resource group must already exist.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ResultFormat

The format of the what-if results. Use FullResourcePayloads (default) to include the full predicted resource bodies, or ResourceIdOnly for a compact list of affected resource IDs.

Parameter properties

Type:String
Accepted values:FullResourcePayloads, ResourceIdOnly
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-SubscriptionId

The Azure subscription ID that owns the target resource group. Defaults to the active profile's subscription when omitted.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateFile

Path to a local ARM JSON or Bicep template file.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateSpecId

Resource ID of an existing template spec to evaluate (for example, /subscriptions/.../providers/Microsoft.Resources/templateSpecs/<spec>/versions/<version>).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateUri

URI of a remote ARM/Bicep template (for example, a blob URL).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ValidationLevel

What-if validation strictness. Common values are Provider (default) and Template. Use a stricter level to catch schema or parameter issues earlier.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Outputs

Microsoft.Azure.Azclips.Extensions.Resources.Models.WhatIfOperationResult

A WhatIfOperationResult describing the changes the deployment would apply if executed. No resources are created or modified; the caller can inspect the change list before running the real deployment.

Notes

What-if is a read-only preview: it never creates or modifies resources. Use New-AzResourceGroupDeployment to apply the changes once the preview looks correct.