PowerShell guidelines for -Confirm, -Force, and -WhatIf
<p>Are there any official guidelines from Microsoft about when to add <code>-Confirm</code>, <code>-Force</code>, and <code>-WhatIf</code> parameters to custom PowerShell cmdlets? There doesn't seem to be a clear consensus about when/how to use these parameters. For example <a href="https://github.com/Azure/azure-powershell/issues/475" rel="noreferrer">this issue</a>.</p>

<p>In the absence of formal guidelines, is there a best practice or rule of thumb to use? Here is some more background, with my current (possibly flawed) understanding:</p>

<h2>-WhatIf</h2>

<p>The <code>-WhatIf</code> flag displays what the cmdlet <em>would do</em> without actually performing any action. This is useful for a dry run of a potentially destabilizing operation, to see what the actual results would be. The parameter is automatically added if the cmdlet's <code>Cmdlet</code> attribute has the <a href="https://msdn.microsoft.com/en-us/library/system.management.automation.cmdletcommonmetadataattribute.supportsshouldprocess(v=vs.85).aspx" rel="noreferrer"><code>SupportsShouldProcess</code></a> property set to true.</p>

<p>It seems like (but I'd love to see more official guidance here) that you should add <code>-WhatIf</code> if you are ever adding or removing resources. (e.g. deleing files.) Operations that update existing resources probably wouldn't benefit from it. Right?</p>

<h2>-Force</h2>

<p>The <code>-Force</code> switch is used to declare "I know what I'm doing, and I'm sure I want to do this". For example, when copying a file (<a href="https://technet.microsoft.com/en-us/library/hh849793.aspx" rel="noreferrer"><code>Copy-File</code></a>) the <code>-Force</code> parameter means:</p>

<blockquote>
  <p>Allows the cmdlet to copy items that cannot otherwise be changed, such as copying over a read-only file or alias.</p>
</blockquote>

<p>So to me it seems like (again, I'd love some official guidance here) that you should add an optional <code>-Force</code> parameter when you have a situation where the cmdlet would otherwise fail, but can be convinced to complete the action.</p>

<p>For example, if you are creating a new resource that will clobber an existing one with the same name. The default behavior of the cmdlet would report an error and fail. But if you add <code>-Force</code> it will continue (and overwrite the existing resource). Right?</p>

<h2>-Confirm</h2>

<p>The <code>-Confirm</code> flag gets automatically added like <code>-WhatIf</code> if the cmdlet has <code>SupportsShouldProcess</code> set to true. In a cmdlet if you call <a href="https://msdn.microsoft.com/en-us/library/system.management.automation.cmdlet.shouldprocess(v=vs.85).aspx" rel="noreferrer"><code>ShouldProcess</code></a> then the user will be prompted to perform the action. And if the <code>-Confirm</code> flag is added, there will be no prompt. (i.e. the confirmation is added via the cmdlet invocation.)</p>

<p>So <code>-Confirm</code> should be available whenever a cmdlet has a big impact on the system. Just like <code>-WhatIf</code> this should be added whenever a resource is added or removed.</p>

<p>With my potentially incorrect understanding in mind, here are some of the questions I'd like a concrete answer to:</p>

<ul>
<li>When should it be necessary to add <code>-WhatIf</code>/<code>-Confirm</code>?</li>
<li>When should it be necessary to add <code>-Force</code>?</li>
<li>Does it ever make sense to support both <code>-Confirm</code> and <code>-Force</code>?</li>
</ul>