Note<\/b> This is Part 4 of a nine-part series about building your own Windows PowerShell cmdlet. Read the entire series<\/a> as it unfolds.<\/p>\n Here’s Sean…<\/p>\n So now what we have is an advanced function that sure feels like a cmdlet, doesn’t it? It almost is, but it needs a lot more polishing. Here are the steps we still need to complete.<\/p>\n Change parameters to accept data as an array<\/p>\n<\/li>\n Add cmdlet binding to emulate compiled cmdlet<\/p>\n<\/li>\n Set properties on parameters and possible validation<\/p>\n<\/li>\n Insert Begin<\/b>, Process<\/b>, and End<\/b> scriptblocks<\/p>\n<\/li>\n Add Help content<\/p>\n<\/li>\n<\/ul>\n When you’re working with a cmdlet, you’re working with the pipeline. Within the pipeline you may receive one object or a large array of them. In both cases you are dealing with an array of information, even if that array only contains one element.<\/p>\n To adjust the parameters as an array, we only need insert a pair of brackets into the variable. This identifies it as an array instead of as a single object.<\/p>\n In the case of our three parameters, they will switch from looking like this…<\/p>\n function global:ADD-LOGFILE{<\/p>\n PARAM(<\/p>\n [STRING]$Folder=”C:\\PowerShell”,<\/p>\n [STRING]$Preface=”Logfile”,<\/p>\n [STRING]$Extension=”.log”<\/p>\n )<\/p>\n …to the following, which allows them to receive data as an array instead of as single parameters.<\/p>\n function global:ADD-LOGFILE{<\/p>\n <\/p>\n PARAM(<\/p>\n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n [STRING[]]$Preface=”Logfile”,<\/p>\n [STRING[]]$Extension=”.log”<\/p>\n )<\/p>\n Cmdlet binding is enabled by adding a new piece before the Param block for your parameters. Cmdlet binding defines how your cmdlet and its parameters will work in the Windows PowerShell world. To enable the cmdlet binding, we simply make this change to our function.<\/p>\n function global:ADD-LOGFILE{<\/p>\n <\/p>\n [CmdletBinding()]<\/p>\n PARAM(<\/p>\n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n [STRING[]]$Preface=”Logfile”,<\/p>\n [STRING[]]$Extension=”.log”<\/p>\n )<\/p>\n Cmdlet binding will bind the parameters in the same fashion as compiled cmdlets. This means parameters that by default are available to all cmdlets are now available to your cmdlet.<\/p>\n With the cmdlet binding, you can also specify additional parameters, such as:<\/p>\n DefaultParameterSetName<\/p>\n<\/li>\n SupportsShouldProcess<\/p>\n<\/li>\n ConfirmImpact<\/p>\n<\/li>\n<\/ul>\n This is what it implies to be. It states which of your parameters should be assumed to be the default. For example, within Add-LogFile<\/b>, we might want to have the folder name as the default parameter. To specify that we would like the folder to be the default parameter for our Add-LogFile<\/b> cmdlet, we would make this change to the top of our advanced function.<\/p>\n function global:ADD-LOGFILE{<\/p>\n <\/p>\n [CmdletBinding(<\/p>\n DefaultParameterSetName=”Folder”<\/p>\n )]<\/p>\n <\/p>\n PARAM(<\/p>\n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n [STRING[]]$Preface=”Logfile”,<\/p>\n [STRING[]]$Extension=”.log”<\/p>\n )<\/p>\n This will allow you to leverage the WhatIf<\/b> parameter. This is my favorite parameter. With this enabled, I can create a cmdlet that has the option to “say without doing” for the user.<\/p>\n Typically, “destructive cmdlets” (those that are intended to remove and cause actions that would be difficult to impossible to undo, such as removing a user in Active Directory) will support this. You can leverage this feature however you would like. It can even be used as part of the troubleshooting for your cmdlet.<\/p>\n We could enable this as part of our cmdlet by adding SupportsShouldProcess<\/b> to CmdletBinding<\/b>.<\/p>\n function global:ADDLOGFILE{<\/p>\n <\/p>\n [CmdletBinding(<\/p>\n DefaultParameterSetName=”Folder”,<\/p>\n SupportsShouldProcess=$True<\/p>\n )]<\/p>\n <\/p>\n PARAM(<\/p>\n [STRING]$Folder=”C:\\PowerShell”,<\/p>\n [STRING]$Preface=”Logfile”,<\/p>\n [STRING]$Extension=”.log”<\/p>\n )<\/p>\n To be able to leverage the SupportsShouldProcess<\/b> parameter, you need to use the following block of script.<\/p>\n If ($PSCmdlet.ShouldProcess(“Message<\/i>“)) { BlockofCode<\/i> }<\/p>\n If the WhatIf<\/b> parameter is supplied with the cmdlet, the contents of “Message” will be displayed, which should indicate what the code block would do. Otherwise, all the script within the parentheses will execute.<\/p>\n If we were to modify Add-LogFile<\/b> to use SupportsShouldProcess<\/b> with our line to create the log file, it would look like this:<\/p>\n If ($PSCmdlet.ShouldProcess(“Creation of Logfile $Logfilename Successful”)) { NEW-ITEM –Type File -path $Logfilename -Force | OUT-NULL }<\/p>\n Now with the feature enabled, we can leverage the WhatIf<\/b> parameter.<\/p>\n ADD-LOGFILE C:\\NewFolder -whatif<\/p>\n The output to the Add-LogFile<\/b> cmdlet that we are creating would now look like this with a controlling WhatIf<\/b> parameter added.<\/p>\n This enables your cmdlet to use the –Confirm<\/b> parameter. This allows you to employ the ability to confirm before actions occur. The script that is required to leverage this feature is identical to SupportsShouldProcess<\/b>.<\/p>\n ConfirmImpact<\/b> is set to one of three values: Low, Medium, or High. It will leverage the value of the $ConfirmPreference<\/b> variable. It will launch a confirmation before the action if it is equal to or greater than the variable or if the –Confirm<\/b> parameter is supplied.<\/p>\n Our same cmdlet using the –Confirm<\/b> parameter would look like this if we added this feature.<\/p>\n function global:ADDLOGFILE{<\/p>\n <\/p>\n [CmdletBinding(<\/p>\n DefaultParameterSetName=”Folder”,<\/p>\n SupportsShouldProcess=$True,<\/p>\n ConfirmImpact=’High’<\/p>\n )]<\/p>\n <\/p>\n PARAM(<\/p>\n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n [STRING[]]$Preface=”Logfile”,<\/p>\n [STRING[]]$Extension=”.log”<\/p>\n )<\/p>\n Running Add-LogFile –Confirm<\/b> with the same changes in the script would look like this.<\/p>\n Let’s save the script as addlogcmdlet.ps1 with our change of [CmdletBinding()]<\/b> placed into it. We’ll run the new script and then execute Get-Help<\/b> on the Add-LogFile <\/b>cmdlet. See if you can catch the difference.<\/p>\n Here it was before the change:<\/p>\n And now after [CmdletBinding()]<\/b> was added:<\/p>\n The difference is that now the common parameters are available. These are parameters that are available to all cmdlets. The common parameters are:<\/p>\n -Verbose<\/p>\n<\/li>\n -Debug<\/p>\n<\/li>\n -WarningAction<\/p>\n<\/li>\n -WarningVariable<\/p>\n<\/li>\n -ErrorAction<\/p>\n<\/li>\n -ErrorVariable<\/p>\n<\/li>\n -OutVariable<\/p>\n<\/li>\n -OutBuffer<\/p>\n<\/li>\n<\/ul>\n All of these options can be leveraged by your cmdlet, depending on how you would like to control the output. In all cases, if your cmdlet receives the parameter but has no script to recognize what it is meant for, it will do nothing.<\/p>\n With the Verbose<\/b> parameter you can set a Boolean True or False as the property. When this parameter is active, data sent by the Write-Verbose<\/b> cmdlet is viewable.<\/p>\n With the Debug<\/b> parameter, you can set a Boolean True or False as the property. When this parameter is active, data sent by the Write-Debug<\/b> cmdlet is viewable.<\/p>\n With the WarningAction<\/b> parameter, you can override the settings contained within $WarningAction<\/b>. When you send data with the Write-Warning<\/b> cmdlet, you have the choice to be prompted for an action.<\/p>\n The WarningVariable<\/b> allows you to store the data sent by Write-Warning into a variable for later retrieval.<\/p>\n With the ErrorAction<\/b> parameter, you can override the settings contained within $ErrorAction<\/b>. The actions of this parameter are similar to WarningAction<\/b> except it is for the Write-Error<\/b> cmdlet. When you send data with the Write-Error<\/b> cmdlet, you can be prompted for an action. Again, the choice is yours.<\/p>\n Like its cousin, the ErrorVariable<\/b> parameter allows you to store errors within a variable.<\/p>\n ~Sean<\/p>\n Thanks Sean! This series is turning out great. I appreciate you hanging in there. Good stuff. Guest Blogger Week will continue tomorrow when Sean will talk more about building a cmdlet.<\/p>\n I invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n Ed Wilson, Microsoft Scripting Guy<\/b><\/p>\n <\/p>\n","protected":false},"excerpt":{"rendered":" Summary: Microsoft Windows PowerShell MVP, Sean Kearney, continues a series of guest blogs that detail how to build your own cmdlet. Microsoft Scripting Guy, Ed Wilson, is here. Guest blogger and Windows PowerShell MVP, Sean Kearney, has written a series about building cmdlets. For more about Sean, see his previous guest blog posts. Note This […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[372,56,3,154,45],"class_list":["post-4883","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-build-your-own-cmdlet","tag-guest-blogger","tag-scripting-guy","tag-sean-kearney","tag-windows-powershell"],"acf":[],"blog_post_summary":" Summary: Microsoft Windows PowerShell MVP, Sean Kearney, continues a series of guest blogs that detail how to build your own cmdlet. Microsoft Scripting Guy, Ed Wilson, is here. Guest blogger and Windows PowerShell MVP, Sean Kearney, has written a series about building cmdlets. For more about Sean, see his previous guest blog posts. Note This […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/4883","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=4883"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/4883\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=4883"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=4883"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=4883"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Polishing the advanced function<\/h2>\n
\n
Change those parameters to an array<\/h2>\n
Enabling cmdlet binding and building on parameters<\/h2>\n
\n
DefaultParameterSetName <\/i><\/h3>\n
SupportsShouldProcess<\/h3>\n
Enable whatif<\/h3>\n
![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/5444.hsg-10-2-12-1.png\" "\\"Image")
<\/a><\/p>\nConfirmImpact <\/i><\/h3>\n
![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/4034.hsg-10-2-12-2.png\" "\\"Image")
<\/a><\/p>\n![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/0726.hsg-10-2-12-3.png\" "\\"Image")
<\/a><\/p>\n![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/3377.hsg-10-2-12-4.png\" "\\"Image")
<\/a><\/p>\n\n