Leveraging -WhatIf command in PowerShell & PowerCLI Scripts

Have you ever been writing a PowerShell or PowerCLI script and wished you could see what would happen if you executed the script just to confirm everything is working properly? Have you ever been been performing single commands that modify the environment and you want to ensure the mod you want is the one applied? I am sure many of you are familiar with the -WhatIf command but for those of you who need a refresher I thought I would write this article.

What is WhatIf:
-WhatIf is a parameter implemented by commands that support PowerShell’s ShouldProcess behavior. It asks that command to report its intended action without performing that action. It does not automatically simulate every command in a script. See Microsoft’s ShouldProcess guidance.

Use the preview to inspect the targets and operations the command reports. It does not prove the operation will succeed, validate every prerequisite, or test the complete script. Connections, lookups, and other commands outside the previewed operation can still run.

Example script that requests actual shutdowns – This first example requests a guest OS shutdown for powered-on VMs matched by the names in a CSV file. It is not a preview. Review the CSV targets and obtain the required authorization before running it.

#vcenter name or IP
$vcenter = “vCenter”
#Path to csv file
$path = “E:\Data\Scripts\listofvms.csv”

connect-viserver $vcenter
$vmlist = import-csv $path | select -ExpandProperty NAME
foreach ($vm in $vmlist) {
Get-VM $vm | Where-Object {$_.powerstate -eq ‘PoweredOn’} | Shutdown-vmguest -Confirm:$false}
Disconnect-VIServer -confirm:$false

Preview script with -WhatIf
This historical example retains the Shutdown-VMGuest command name. The guard below stops if that command is unavailable or does not expose -WhatIf in the installed PowerCLI version. Apply the parameter to the shutdown command inside the loop. Disconnect-VIServer closes server connections; adding -WhatIf there cannot protect earlier shutdown commands.

# vCenter name or IP
$vcenter = 'vCenter'
# Path to a CSV file with a NAME column
$path = 'E:\Data\Scripts\listofvms.csv'

$shutdownCommand = Get-Command -Name Shutdown-VMGuest -ErrorAction Stop
if ($null -eq $shutdownCommand.Parameters -or
    -not $shutdownCommand.Parameters.ContainsKey('WhatIf')) {
    throw 'This installed Shutdown-VMGuest command does not expose -WhatIf. Stop and check the help for your PowerCLI version.'
}

$connection = Connect-VIServer -Server $vcenter -ErrorAction Stop
try {
    $vmlist = Import-Csv -Path $path | Select-Object -ExpandProperty NAME
    foreach ($vm in $vmlist) {
        Get-VM -Name $vm -Server $connection -ErrorAction Stop |
            Where-Object { $_.PowerState -eq 'PoweredOn' } |
            Shutdown-VMGuest -WhatIf -ErrorAction Stop
    }
}
finally {
    Disconnect-VIServer -Server $connection -Confirm:$false
}

Result:
The preview passes -WhatIf to each guest-shutdown request so a supporting command reports the intended action instead of requesting the shutdown. The server connection, CSV import, VM lookups, and final disconnect still run. Review the reported VM targets, but do not treat the preview as proof that a later shutdown will succeed. Validate VMware Tools, permissions, and operational prerequisites separately. Broadcom’s current guest-shutdown reference also notes that the command returns before the guest completes its shutdown.

Summary:
I use -WhatIf to preview supported commands before making changes. It helps review intended actions and targets, but it does not replace testing and validation of the full workflow. As always, I hope y’all found this article useful.