Geek Answers Handbook

PowerShell Recommendations for -Confirm, -Force, and -WhatIf

Are there any official Microsoft recommendations on when to add the -Confirm , -Force and -WhatIf to custom PowerShell cmdlets? There seems to be no clear consensus on when / how to use these parameters. For example, this problem .

In the absence of formal guidelines, is there a best practice or rule of thumb? Here are some more stories, with my current (possibly erroneous) understanding:

-WhatIf

The -WhatIf flag indicates what the cmdlet will do without performing any action. It is useful to dry run a potentially destabilizing operation to see what the actual results will be. The parameter is automatically added if the cmdlet attribute of Cmdlet has the SupportsShouldProcess property set to true.

It seems that (but I would like to see a more formal guide here) that you should add -WhatIf if you ever add or remove resources. (for example, deleting files.) Operations that update existing resources will probably not benefit from this. Correctly?

-Force

The -Force switch -Force used to declare "I know what I'm doing, and I'm sure I want to do this." For example, when copying a file ( Copy-File ), the -Force means:

Allows the cmdlet to copy items that cannot otherwise be changed, such as copying by file or read-only alias.

So it seems to me (again, I would like some official recommendations here) that you should add the optional -Force parameter when you have a situation where the cmdlet otherwise fails, but you can verify the action.

For example, if you create a new resource that will clobber existing with the same name. The default cmdlet behavior will report an error and fail. But if you add -Force , it will continue (and overwrite the existing resource). Correctly?

-Confirm

The -Confirm flag -Confirm automatically added as -WhatIf if the cmdlet has SupportsShouldProcess set to true. In the cmdlet, if you call ShouldProcess , the user will be prompted to perform an action. And if the -Confirm flag is -Confirm , there will be no invitation. (that is, confirmation is added through a call to the cmdlet.)

So, -Confirm should be available whenever the cmdlet has a big impact on the system. Just like -WhatIf , this should be added when adding or removing a resource.

Given my potentially misunderstanding, here are some of the questions I would like to answer in a concrete way:

  • When do I need to add -WhatIf / -Confirm ?
  • When to add -Force ?
  • Does it make sense to support both -Confirm and -Force ?
+8
powershell
source share
3 answers

I have not investigated whether the documentation is detailed, but the following data are based on my observations:

  • You should use -WhatIf for anything that makes a difference. Updates are changes that can benefit from -WhatIf (for example, what if you want to make a lot of updates?).

  • -Force means "force overwrite an existing item" or "override a read-only file system attribute". In any case, the success of the action depends on the user who has permission.

  • -Confirm and -Force are not mutually exclusive. For example, you can confirm the action for writing a file, but the file can be protected with a read-only attribute. In this case, the action will fail if you do not specify -Force .

+5
source share

If you want to confirm that your implementation of these general parameters is as recommended (for example, Set-Xxx cmdlets should have -Confirm and -WhatIf), then you can use the excellent PsScriptAnalyzer module (which is based on code analysis).

Make sure the module is installed:

 PS E:\> Install-Module -Name 'PsScriptAnalyzer'

Then do a PowerShell code analysis as follows:

 PS E:\> Invoke-ScriptAnalyzer -Path . | FL RuleName : PSUseShouldProcessForStateChangingFunctions Severity : Warning Line : 78 Column : 10 Message : Function 'Update-something' has verb that could change system state. Therefore, the function has to support 'ShouldProcess'.

The documentation (and sources) can be found on GitHub: https://github.com/PowerShell/PSScriptAnalyzer

+1
source share

As an additional observation, -Force does not cancel -WhatIf . Or in other words: -WhatIf takes precedence over -Force .

If you use:

 Get-ChildItem -Recurse | Remove-Item -Recurse -Force -WhatIf

this will lead to the following conclusion:

What to do: Perform the operation "Delete directory" in the target "E: \ some directory \".

It does not actually remove items, even if -Force is -Force .

This means that you should never write:

 if($Force -or $Pscmdlet.ShouldProcess($)) { ... }
0
source share

More articles:


All Articles