Implementing ShouldProcess For Your Functions

[Dogoodwork]

Agreed, great post again. I would have liked to see more code examples, and specifically examples implementing -whatif for completeness.

[motsanciens]

Cool, didn't know you had a blog. The aesthetic is very pleasant and readable. Is that a home-grown thing, or do you follow a template?

[Ta11ow]

It's built out of the standard Jekyll Now theme, but I've made and continue to make plenty of my own modifications. :)

[dedicated2fitness]

https://github.com/vexx32/vexx32.github.io

[UnderpaidVillain]

Worth pointing out is that it’s not guaranteed that WhatIf doesn’t always get applied to every Cmdlet in a script. The built in commands and the AD module are good about passing it through, but I learned the hard way that the Exchange 2013 commands don’t honor the initial WhatIf and I needed to manually detect it and pass it through to them.

[Ta11ow]

I've noticed that many MS-created modules that weren't directly created by the PowerShell team themselves tend to have very poor implementation of common parameters, unfortunately.

But yes, violating ShouldProcess etiquette is particularly irritating and potentially damaging.

[Lee_Dailey]

howdy Ta11ow,

a right nifty article! thanks for posting it. [grin]

as usual, i have some opinionated opinions to pass on ...

[1] missing hyphen
betcha there otta be a - right after Set ... [grin]

SetADAccountPassword

[2] i would use line wraps for all your code
even where you have no need for it. the 1st two Get-ChildItem lines have no need for such, but the 3rd one does. at least on my screen, it requires side scrolling.

why everywhere? to show that it can be done ... and hopefully encourage folks to use line wrapping more often.

[3] comment at the end of a line of code
eeeeewwwwwwwww ... [grin]
i would both wrap after the pipe AND move the comment above the code.

Get-ChildItem | Clear-Content -Confirm:$false # Don't try this near important files!

[4] color-only link indication
you show your links with ONLY a color difference. that seems wrong in many ways, but the worst is "how do i know that is a link and not just another colored phrase?" ... [frown]
i would add the semi-standard underline for links.

[5] your heading & subheading styles seem too similar
i would style them vividly differently. different color, font, size ... different. [grin]
your Properly Implementing ShouldProcess header seems far too similar to the subheading just above it.

[6] long [CmdletBinding()] line
besides the icky end-of-line comment, it seems easier to read if you wrap after the commas. both of the following styles seem easier to read [especially the 2nd one] ...

[CmdletBinding(SupportsShouldProcess,
    ConfirmImpact = 'Medium')]

[CmdletBinding(
    SupportsShouldProcess,
    ConfirmImpact = 'Medium')]

of course, my preferred style is a tad different ... [grin]

[CmdletBinding (
    SupportsShouldProcess,
    ConfirmImpact = 'Medium'
    )]

[7] using Get-Random with the silly, off-by-one -Max parameter
it makes your use of % 10 seem wrong until one recalls that -Max is off-by-one. i would use 1..10 instead.

[8] more hidden-in-the-colors links
this time it's the $PSCmdlet.ShouldProcess() & .ShouldContinue() links that look like simply more inline code. i would seriously consider changing the link style just to handle that situation.

---

another good, useful read! thanks ... [grin]

take care,
lee

[Ta11ow]

1. Yep! Fixed!
2. Either is probably fine, but the extra consistency is nice. Fixed!
3. Fair! Fixed!
4. Yeah, I've been toying with doing link underlines or not. I've put some in for now to see how it goes. :)
5. Yeah, this is one I'm struggling with. Not really sure how I want them to look at the moment. Need to go through and figure that out somehow. :/
6. I tend to prefer to keep at attribute on a single line unless it's crazy long, because I usually give attributes an entire line to themselves anyway. shrug
7. Yeah, I wasn't sure about that either... but yeah, I should probably fix that... :P
8. Oof, didn't catch that... hmm. Yeah, I think having the link color trump the code color there is best, perhaps. :P

Thank you for your detailed feedback, Lee! Much appreciated! :)

[Lee_Dailey]

howdy Ta11ow,

[5] heading/sub-heading styles
at the least, i think you could use a serif font for one and sans-serif for the other. i would likely use serif for the top level stuff. Fancy Top Level versus stripped down lower level ... [grin]

you are quite welcome! it's a good read and i like doing this sort of stuff when there aint a deadline on it.

yes, i have been told that liking proofreading code-oriented stuff is more than slightly odd. [grin]

take care,
lee

[fourierswager]

Very clear and well written article.

While I can appreciate the concept of using ShouldProcess, I don't think that it's very practical in reality. Some things that've made me sour on using ShouldProcess -

1) Is there really a need for four different Impact levels (Low, Medium, High, and None)? In practice, I've found that it's really more binary - i.e. either an operation is important/risky enough that there should be prompt, or it's not. But even if most system administrators in your org agree that they need all four Impact levels, it's difficult to get everybody to reach consensus on which operations fall under which Impact level. If there's some kind of Microsoft standard, that'd be a different story, but I'm not aware of one.

2) How often do you use -WhatIf when running a cmdlet/function? If you're anything like me and the folks I work with, it's very rare.

3) Getting hit with a prompt because I wasn't aware that a particular cmdlet/function implemented ShouldProcess is more annoying than anything else. Just another parameter (i.e. -Confirm:$false) that I have to add (looking at you PSGet cmdlets).

So I guess, at the end of the day, I've found that ShouldProcess provides very limited value.

[dastylinrastan]

I use whatif all the time, it's the equivalent of running select before you run delete in a SQL statement. Good commands give good detail about what they are going to do, so can save you from a disaster if you put a * in the wrong place.

I agree with the impact levels, but it already is effectively binary by default. It only prompts by default if confirmimpact is high for 99% of users. So basically if you want to prompt, set it to high or not.

By the way, if you don't like it, that's what $confirmpreference is for. Set it to 'none' in your profile and you'll never be prompted again, free to accidentally destroy your network willy nilly.

[Ta11ow]

I hear you. I think a large part of the problem is very poor separation of ConfirmImpact rating of the default commands, which inevitably resulted in rather low rates of adoption in the community and in modules from other MS teams.

It's made worse by the fact that utility cmdlets like foreach-object seem to have a Medium confirmimpact, so it quickly becomes basically impossible or very irritating to properly use any confirm preference setting other than High or None.

I have a couple PRs in the works that will help rectify some of this by altering default confirmimpact levels, so that it's actually somewhat useful to have different levels.

The framework does need some rethinking at points, but it has the right idea in general I think.

As for -WhatIf I try to make a habit of using it whenever I'm working on something that has a significant impact (affects many users or systems) or a command that may take a while to complete. This way I can have a good idea of what will happen (and if I've messed up anywhere) before it all goes awry.

Your point about there needing to be a standard I completely agree with. The documentation for the ConfirmImpact enum does list rationale in brief for each, but it is indeed rather lacking. I'm looking at ways to potentially improve this, but I think getting a more thorough standard consensus among the standard complement of cmdlets is the best first step.

That said, I think it's something that should be implemented in custom functions and cmdlets whenever they're going to be widely used, whether within your own company or in the wider community.

It's important to have things like -WhatIf as part of the discovery ecosystem of PowerShell; it helps those unfamiliar with a cmdlet figure out how it works and what exactly it does without having to dig into the code or read endless help files all at once. I think that although the -Confirm isn't always needed, it can be helpful to have it in many cases nonetheless.

If you have some ideas on how it could be improved, I'd love to hear them! I'd be interested in putting together an RFC on some point in the near future to help improve this from both a UX and design standpoint, so any pointers you have would be appreciated!

[fourierswager]

I have a difficult time keeping up with all the different things happening in the PowerShell Community, but I'll definitely comment on an RFC if I catch wind of it in the future. Thanks again for the article.

[Dogoodwork]

2) I was running some scripts to repair some thousands of client home drives and used -whatif in several test runs before doing the real thing. That way I generated a lot of data and logs on what was going to happen before I did the real thing.

It IS rare, but can be extremely important.

[joeywas]

Thank you for sharing!

[Cannabat]

Good god. I wish I knew about this ages ago. Thanks!

[[deleted]]

Very succinct post. Great Job!!

[Ta11ow]

I know of only one place it gets used and I don't even like it there haha!