Confirm, $ConfirmPreference, and ConfirmImpact in PowerShell

• Author
• Recent Posts

Adam Bertram

Adam Bertram is a 20-year IT veteran, Microsoft MVP, blogger, and trainer.

Latest posts by Adam Bertram (see all)

• Create a certificate-signed RDP shortcut via Group Policy - Fri, Aug 9 2019
• Monitor web server uptime with a PowerShell script - Tue, Aug 6 2019
• How to build a PowerShell inventory script for Windows Servers - Fri, Aug 2 2019

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

$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.

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

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

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.

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).