Share via

Scripting Tips and Tricks: CmdletBinding()

  • Article

It's been a little while since we've had a Scripting Tips and Tricks post... and, boy, what a topic to return on - CmdletBinding!

The last Tips and Tricks post talked about using Write-Verbose in scripts and advanced functions. It's just one of the features enabled with CmdletBinding. Here's a snippet of what I had to say last time out:

"...With version 2 of PowerShell 'advanced functions' made their debut. These are functions that act like cmdlets. To enable this goodness we use the CmdletBinding statement. In doing so we have easy access to a wealth of additional, familiar functionality, e.g. common parameters..."

We've mentioned common parameters and here they are:

  • -Verbose
  • -Debug
  • -ErrorAction
  • -WarningAction
  • -ErrorVariable
  • -WarningVariable
  • -OutVariable
  • -OutBuffer
  • -PipeLineVariable

 

Access to these parameters is granted with CmdletBinding in its simplest form. The below example should be placed at the top of a script or function.

[CmdletBinding()]

Param()

Notice the Param statement. The metadata controlled by CmdletBinding is part of the Param declaration. What do I mean by metadata? Well, CmdletBinding allows us to define properties that apply to a whole script or function. Take a look at this example:

[CmdletBinding(SupportsShouldProcess)]

Param()

 

This now gives us access to the 'risk mitigation' parameters:

  • -WhatIf
  • -Confirm

 

WhatIf gives you a summary of what the script or function will attempt to do. Confirm provides a 'do you really want to do that?' type message. To make proper use of these beauties we need to add a little extra something to an advanced function:

function Get-ADUserGroupMembership {

[CmdletBinding(SupportsShouldProcess)]

Param($User)

If ($PSCmdlet.ShouldProcess($User, "Enumerate MemberOf attribute")) {

(Get-ADUser -Identity $User -Property MemberOf).MemberOf

}

}

Notice the PSCmdlet variable. It has a method - ShouldProcess() - that accepts two strings:

  • The first string is the object the action is being performed on.
  • The second string is a summary of what the action is going to be.

 

This is all part of an if statement.

Now, when a -WhatIf parameter is supplied to the function we get a message telling us what's going to happen in the script block following our $PSCmdlet.ShouldProcess() condition.

 

Cool! We also have the ability to use -Confirm.

This time we get the ShouldProcess() message and some execution options: carry on, stop, suspend*

*NB [S] Suspend let's us enter the execution scope for debugging (more on this in a future post).

 

Finally, consider exploring the other options available with the CmdletBinding statement.

Get-Help about_Functions_CmdletBindingAttribute

Comments

  • Anonymous
    October 24, 2014
    Thanks
    always interesting
  • Anonymous
    March 14, 2017
    Very useful post.In return, can I point out a small typo, please? In the section "This now gives us access to the 'risk mitigation' parameters:"WhaIf needs to be WhatIf (of course!)
    • Anonymous
      March 21, 2017
      Thanks!