There are a few ways to ensure your PowerShell functions don't cause damage. In this article, I'll focus on the -Confirm parameter, the $ConfirmPreference variable, and the ConfirmImpact argument.

Let's say you're a US defense contractor and have a function called Invoke-NuclearMissleTest. Would you say this PowerShell script is important? Chances are, if the name accurately represents the contents of the function, you're going to treat this function with kid gloves. After all, if this function ran accidentally, World War 3 might break out. I think you'd agree that we should place some safeguards around this.

A typical IT professional's script is probably not going to start a world war. But I'm sure some of you out there have scripts that could cause some damage to production systems. If so, have you placed the necessary safeguards around those scripts to ensure they do not execute inappropriately? I myself have some horror stories, but we'll save those for a later time.

The -Confirm Parameter

Most PowerShell cmdlets incorporate Confirm functionality. When used, this forces PowerShell to prompt the user before performing an action. For example, stopping a process is a simple task with the Stop-Process cmdlet.

Stop-Process -Name notepad

What if a script stops an important production process? You might want to include some safeguards around that. To do that, you could use the Confirm parameter on the Stop-Process command. The Confirm parameter forces all commands that have this functionality built in to prompt the user before performing any potentially destructive action.

Using the Confirm parameter

Using the Confirm parameter

$ConfirmPreference and ConfirmImpact

Notice now before stopping the process, it asks me if I'm sure. This is the standard Confirm functionality. Note that I mentioned that functions must have this functionality built in. For this to work, the cmdlet or advanced function must have the code to handle it. Luckily, we can make this happen in our advanced functions.

To understand more about how the Confirm functionality works under the covers, you first need to understand the built-in confirm levels in PowerShell. PowerShell has three confirm levels: High, Medium, and Low. The $ConfirmPreference automatic variable sets these levels.

By default, PowerShell sets this variable to High. The level this is set at depends on what happens when calling a cmdlet or advanced function without using the Confirm parameter.

We can categorize each advanced function as having a specific ConfirmImpact level by using the ConfirmImpact keyword inside of the function. As you may have guessed, this can be High, Medium, or Low depending on how important it is to prompt the user. If $ConfirmPreference is set to the same or a higher level than the level in the function, PowerShell will prompt the user for confirmation.

Perhaps you've got a function that should prompt the user every time, but you're always forgetting to use the Confirm parameter. Setting the impact level in the function to High can achieve this.

function Invoke-NuclearMissleTest {
    SupportsShouldProcess = $true,
    ConfirmImpact = 'High')]
    if ($PSCmdlet.ShouldProcess($param)) {
        Write-Output 'Nuclear missile launched!'

Rhe SupportsShouldProcess argument, enable users to add the ‑Confirm parameter. The automatic variable $PScmdlet allows you to access properties and methods built in within all advanced functions. In the example, I use the ShouldProcess method that provides the confirmation functionality.

My function has a high Confirm severity. I'd like to prompt for confirmation all the time regardless of whether I choose -Confirm and regardless of how $ConfirmPreference is configured.

PowerShell function asks for confirmation

PowerShell function asks for confirmation

If the $ConfirmPreference value is set to be lower than the impact that my function has, it will automatically prompt the user.

For instance, if you set the ConfirmImpact level in your function to Medium, a confirmation prompt will only appear if $ConfirmPreference is set to Medium or Low. If $ConfirmPreference is set to High, this will only produce a prompt if the user adds the ‑Confirm parameter.

Subscribe to 4sysops newsletter!

PowerShell's confirmation ability gives the scripter ultimate control over what commands to execute. If you're not using this already, try it out. You never know when one of those scripts of yours might execute accidentally and create an RGE (resume generating event).

  1. Avatar
    drowa 6 years ago

    In this case the default answer should be “No” instead of “Yes”, don’t you think?

  2. Avatar
    Manuel Berfelde 5 years ago

    I wonder why cmdlets like Remove-Item, Restart-Computer and Set-Acl have the same ConfirmImpact value (medium) like Format-Table, Get-Date and Out-Null.

    The impact of those two groups of cmdlets is way different.

  3. Avatar
    Joe 3 years ago

    Another powershell statement uses this command

    Stop-Process -Name notepad


    But want to provide 'L' as the answer and continue to the next statement. Is it possible to select 'L' ?

Leave a reply

Please enclose code in pre tags: <pre></pre>

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2023


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account