how to use 'dry-run' in powershell

Question

I'm just a starter, dry-run is pretty useful to make a parameter to test, can any body tell me how to use it with an easy way? I googled that but few results on its uses.

Thank you very much

Answer 1

Use on existing cmdlets

Explicitly supply the -WhatIf parameter:

rm foo.txt -WhatIf

Result:

What if: Performing operation "Remove File" on Target "C:\temp\foo.txt".

Use on existing cmdlets within a function or script

SupportsShouldProcess attribute automatically propagates -WhatIf to supported cmdlets:

function do-stuff
{
    [CmdletBinding(SupportsShouldProcess=$True)]
    param([string]$file)
    Remove-Item $file
}

do-stuff foo.txt -WhatIf

Result:

What if: Performing operation "Remove File" on Target "C:\temp\foo.txt".

Use on your own code blocks

Explicitly use ShouldProcess() method to determine whether -WhatIf was passed:

function do-stuff
{
    [CmdletBinding(SupportsShouldProcess=$True)]
    param([string]$file)
    if ($PSCmdlet.ShouldProcess($file)) {
        Write-Host "Deleting file"
        Remove-Item $file
    }
}

do-stuff foo.txt -WhatIf

Result:

What if: Performing operation "do-stuff" on Target "foo.txt".

Use on Nested functions in the same module

SupportsShouldProcess attribute automatically propagates -WhatIf to nested functions:

function do-stuff
{
    [CmdletBinding(SupportsShouldProcess=$True)]
    param([string]$file)
    if ($PSCmdlet.ShouldProcess($file)) {
        Write-Host "Deleting file"
        Remove-Item $file
    }
    inner "text"
}

function inner
{
    [CmdletBinding(SupportsShouldProcess=$True)]
    param([string]$s)
    if ($PSCmdlet.ShouldProcess($s)) {
        Write-Host "Inner task"
    }
    $s | out-file "temp9.txt"
}
do-stuff foo.txt -WhatIf

Result:

What if: Performing operation "do-stuff" on Target "foo.txt".
What if: Performing operation "inner" on Target "text".
What if: Performing operation "Output to File" on Target "temp9.txt".

Use on Nested functions in a different module

Unfortunately, -WhatIf does not propagate automatically to functions defined in a different module. See Powershell: How to get -whatif to propagate to cmdlets in another module for discussion and workaround for this.

Answer 2

You are probably referring to the -WhatIf and -Confirm parameters on cmdlets. You can read up about them in Get-Help about_commonParameters:

Risk Management Parameter Descriptions

-WhatIf[:{$true | $false}]

Displays a message that describes the effect of the command, instead of executing the command.

WhatIf parameter overrides the value of the $WhatIfPreference variable for the current command. Because the default value of the $WhatIfPreference variable is 0 (disabled), WhatIf behavior is not performed without the WhatIf parameter. For more information, type the following command:

get-help about_preference_variables

Valid values:

$true (-WhatIf:$true). Has the same effect as -WhatIf.
$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior that results when the value of the $WhatIfPreference variable is 1.

For example, the following command uses the WhatIf parameter in a Remove-Item command:

PS> remove-item date.csv -whatif

Instead of removing the item, Windows PowerShell lists the operations it would perform and the items that would be affected. This command produces the following output:

What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".

-Confirm[:{$true | $false}]

Prompts you for confirmation before executing the command.

The Confirm parameter overrides the value of the $ConfirmPreference variable for the current command. The default value is High. For more information, type the following command:

get-help about_preference_variables

Valid values:

$true (-WhatIf:$true). Has the same effect as -Confirm.
$false (-Confirm:$false). Suppresses automatic confirmation, which occurs when the value of $ConfirmPreference is less than or equal to the estimated risk of the cmdlet.

For example, the following command uses the Confirm parameter with a Remove-Item command. Before removing the item, Windows PowerShell lists the operations it would perform and the items that would be affected, and asks for approval.

PS C:\ps-test> remove-item tmp*.txt -confirm

This command produces the following output:

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend
[?] Help (default is "Y"):