Note<\/b> This is Part 6 of a nine-part series about building your own Windows PowerShell cmdlet. Read the entire series<\/a> as it unfolds.<\/p>\n<\/p>\n Here’s Sean…<\/p>\n<\/p>\n If you don’t enable [CmdletBinding()]<\/b>, you can still extend features of your advanced function as a cmdlet. This is done by preceding a parameter name or names with the argument [parameter()].<\/b><\/p>\n<\/p>\n The additional properties you can send with [parameter()]<\/b> are:<\/p>\n<\/p>\n Mandatory<\/p>\n<\/li>\n Position<\/p>\n<\/li>\n ValueFromPipeline<\/p>\n<\/li>\n ValueFromPipelineByPropertyName<\/p>\n<\/li>\n ValueFromRemainingArguments<\/p>\n<\/li>\n HelpMessage<\/p>\n<\/li>\n Alias<\/p>\n<\/li>\n<\/ul>\n Each of these properties has a purpose reflective of its name. This makes them quite easy to use and remember their purpose.<\/p>\n<\/p>\n As you would have guessed, Mandatory<\/b> means that this parameter absolutely must be in the pipeline. If it does not receive data, the cmdlet will prompt for the value. A good example of a mandatory parameter would be the path in Remove-Item. This cmdlet cannot function unless it knows what to remove. This would be mandatory for it to function.<\/p>\n<\/p>\n If we want to make the $FolderName<\/b> parameter mandatory in our cmdlet, we would modify it in the following fashion.<\/p>\n<\/p>\n function global:ADD-LOGFILE{<\/p>\n \n <\/p>\n \n [CmdletBinding(<\/p>\n \n DefaultParameterSetName=”Folder”,<\/p>\n \n SupportsShouldProcess=$True,<\/p>\n \n ConfirmImpact=’High’<\/p>\n \n )]<\/p>\n \n <\/p>\n \n PARAM(<\/p>\n \n <\/p>\n \n [parameter(Mandatory=$True)<\/p>\n \n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n \n <\/p>\n \n [STRING[]]$Preface=”Logfile”,<\/p>\n \n [STRING[]]$Extension=”.log”<\/p>\n \n )<\/p>\n<\/p>\n Position is simpler to deal with. If you would like users to run your cmdlet without keying in the parameter names, you can specify positions for certain parameters. For example, even though I can execute the following cmdlet…<\/p>\n<\/p>\n GET-CHILDITEM –literalpath C:\\MyFolder<\/p>\n<\/p>\n …I can equally execute this cmdlet:<\/p>\n<\/p>\n GET-CHILDITEM C:\\MyFolder<\/p>\n<\/p>\n Why is that? Because the assigned position of the LiteralPath<\/b> parameter is 1<\/b>, as we can see from Get-Help<\/b>.<\/p>\n<\/p>\n With the position parameter, we can make it easier for users to execute cmdlets with parameters they might typically use. We can do the same thing to our current set of parameters.<\/p>\n<\/p>\n By default, if you don’t define this, Windows Powershell will assign a position based on the order that you define the parameters. It is recommended as a best practice to always assign the position when defining the parameters. You’ll find things don’t break later on when you go to add additional parameters as you need changes.<\/p>\n<\/p>\n function global:ADD-LOGFILE{<\/p>\n \n <\/p>\n \n [CmdletBinding(<\/p>\n \n DefaultParameterSetName=”Folder”,<\/p>\n \n SupportsShouldProcess=$True,<\/p>\n \n ConfirmImpact=’High’<\/p>\n \n )]<\/p>\n \n <\/p>\n \n PARAM(<\/p>\n \n <\/p>\n \n [parameter(Mandatory=$True),<\/p>\n \n Position=0]<\/p>\n \n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n \n <\/p>\n \n [parameter(Position=1)]<\/p>\n \n [STRING[]]$Preface=”Logfile”,<\/p>\n \n <\/p>\n \n [parameter(Position=2)]<\/p>\n \n [STRING[]]$Extension=”.log”<\/p>\n \n )<\/p>\n<\/p>\n You may or may not (because the design is completely in your hands) want to have a parameter accept data from the pipeline. This property is strictly a Boolean True or False setting. It specifies that a parameter can accept input from the pipeline. We can leverage this feature in our cmdlet by changing our parameters in the following manner.<\/p>\n<\/p>\n function global:ADD-LOGFILE{<\/p>\n \n <\/p>\n \n [CmdletBinding(<\/p>\n \n DefaultParameterSetName=”Folder”,<\/p>\n \n SupportsShouldProcess=$True,<\/p>\n \n ConfirmImpact=’High’<\/p>\n \n )]<\/p>\n \n <\/p>\n \n PARAM(<\/p>\n \n <\/p>\n \n [parameter(Mandatory=$True,<\/p>\n \n ValueFromPipeline=$True,<\/p>\n \n Position=0)]<\/p>\n \n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n \n <\/p>\n \n [parameter(ValueFromPipeline=$True,<\/p>\n \n Position=1)]<\/p>\n \n [STRING[]]$Preface=”Logfile”,<\/p>\n \n <\/p>\n \n [parameter(ValueFromPipeline=$True,<\/p>\n \n Position=1)]<\/p>\n \n [STRING[]]$Extension=”.log”<\/p>\n \n )<\/p>\n<\/p>\n This is similar to the prior parameter, but it specifies the actual property name that the parameter can accept from the pipeline. A good example to work with is Get-ChildItem<\/b>. When the Get-ChildItem<\/b> cmdlet is run against the file system, it returns multiple properties such as FullName<\/b>, Extension<\/b>, DirectoryName<\/b>, and LastAccessTime<\/b> amongst others as shown in the following example.<\/p>\n<\/p>\n If we want to ensure that a parameter only accepts data from the pipeline when the property name is Extension<\/b>, we can make this change to a parameter. We can tell the Add-LogFile<\/b> cmdlet that we are building to accept the Extension<\/b> property if passed through the pipeline.<\/p>\n<\/p>\n function global:ADD-LOGFILE{<\/p>\n \n <\/p>\n \n [CmdletBinding(<\/p>\n \n DefaultParameterSetName=”Folder”,<\/p>\n \n SupportsShouldProcess=$True,<\/p>\n \n ConfirmImpact=’High’<\/p>\n \n )]<\/p>\n \n <\/p>\n \n PARAM(<\/p>\n \n <\/p>\n \n [parameter(Mandatory=$True,<\/p>\n \n ValueFromPipeline=$True,<\/p>\n \n Position=0)]<\/p>\n \n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n \n <\/p>\n \n [parameter(ValueFromPipeline=$True,<\/p>\n \n Position=1)] <\/p>\n \n [STRING[]]$Preface=”Logfile”,<\/p>\n \n <\/p>\n \n [parameter(ValueFromPipeline=$True,<\/p>\n \n Position=1,<\/p>\n \n ValueFromPipelineByPropertyName=$True)]<\/p>\n \n [STRING[]]$Extension=”.log”<\/p>\n \n )<\/p>\n<\/p>\n When you use this parameter, it identifies that any data coming down the pipeline that is not already assigned to other parameters will be accepted by this variable.<\/p>\n<\/p>\n There is nothing better for a user than being a little bit helpful. The Help message is a simple bit of text that you can provide to explain what this parameter is. In the case of the cmdlet we are building, it can be as simple as, “Folder to place log files in.” Here is a simple example of the HelpMessage<\/b> put to use in our cmdlet.<\/p>\n<\/p>\n function global:ADD-LOGFILE{<\/p>\n \n <\/p>\n \n [CmdletBinding(<\/p>\n \n DefaultParameterSetName=”Folder”,<\/p>\n \n SupportsShouldProcess=$True,<\/p>\n \n ConfirmImpact=’High’<\/p>\n \n )]<\/p>\n \n <\/p>\n \n PARAM(<\/p>\n \n <\/p>\n \n [parameter(Mandatory=$True,<\/p>\n \n ValueFromPipeline=$True,<\/p>\n \n Position=0,<\/p>\n \n HelpMessage=’Folder to Store Logfiles in’)]<\/p>\n \n [STRING[]]$Folder=”C:\\PowerShell”,<\/p>\n \n <\/p>\n \n [parameter(ValueFromPipeline=$True,<\/p>\n \n Position=1,<\/p>\n \n HelpMessage=’TEXT to prepend all logfiles with’)]<\/p>\n \n [STRING[]]$Preface=”Logfile”,<\/p>\n \n <\/p>\n \n [parameter(ValueFromPipeline=$True,<\/p>\n \n Position=1,<\/p>\n \n ValueFromPipelineByPropertyName=$True,<\/p>\n \n HelpMessage=’File Extension for Logfiles’)]<\/p>\n \n [STRING[]]$Extension=”.log”<\/p>\n \n )<\/p>\n<\/p>\n If we ran our cmdlet now and did not provide any information for the Folder<\/b> parameter (because it is a MandatoryParameter<\/b>), we would see the Help message echoed in this fashion.<\/p>\n<\/p>\n Our Folder<\/b> parameter now has a simple line of text to explain its purpose if needed. As part of the features of the cmdlet, Windows Powershell allows the user to enter “!?” to pull up that simple line of Help.<\/p>\n<\/p>\n An alias allows you to provide alternate names that a parameter can accept data with. The parameter name itself will not change; but in the case of AcceptValueByPropertyName<\/b>, we can give a parameter multiple names to accept the data with automatically.<\/p>\n<\/p>\n In the case of Folder<\/b>, we could choose to use an alias of Path<\/b> or Destination<\/b> if that made more sense.<\/p>\n<\/p>\n You can apply various attributes that allow you to indicate how values sent into the parameters should be dealt with or how they can be referred to alternate. Validation attributes are added like the other parameter attributes, and they can allow us to validate data being passed into the cmdlet or to specify what the cmdlet does not permit for certain parameters. The validation attributes that are available to us are:<\/p>\n<\/p>\n AllowNull<\/p>\n<\/li>\n AllowEmptyString<\/p>\n<\/li>\n AllowEmptyCollection<\/p>\n<\/li>\n ValidateCount<\/p>\n<\/li>\n ValidateLength<\/p>\n<\/li>\n ValidatePattern<\/p>\n<\/li>\n ValidateRange<\/p>\n<\/li>\n ValidateScript<\/p>\n<\/li>\n ValidateSet<\/p>\n<\/li>\n ValidateNotNull<\/p>\n<\/li>\n ValidateNotNullOrEmpty<\/p>\n<\/li>\n<\/ul>\n ~Sean<\/p>\n<\/p>\n Thank you, Sean. You absolutely ROCK! Guest Blogger Week will continue tomorrow when Sean will bring us Part 7.<\/p>\n<\/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<\/p>\n Ed Wilson, Microsoft Scripting Guy<\/b><\/p><\/p>\n","protected":false},"excerpt":{"rendered":" Summary: Microsoft Windows PowerShell MVP, Sean Kearney, continues a series of guest blogs detailing building 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 is Part 6 […]<\/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-4871","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 detailing building 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 is Part 6 […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/4871","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=4871"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/4871\/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=4871"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=4871"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=4871"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Parameters within cmdlets<\/h2>\n<\/p>\n
\n
Mandatory<\/h3>\n<\/p>\n
Position<\/h3>\n<\/p>\n
![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/6266.hsg-10-4-12-1.png\" "\\"Image")
<\/a><\/p>\n<\/p>\nValueFromPipeline<\/h3>\n<\/p>\n
ValueFromPipelineByPropertyName<\/h3>\n<\/p>\n
![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/2867.hsg-10-4-12-2.png\" "\\"Image")
<\/a><\/p>\n<\/p>\nValueFromRemainingArguments<\/h3>\n<\/p>\n
HelpMessage<\/h3>\n<\/p>\n
![\"Image](\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/2766.hsg-10-4-12-3.png\" "\\"Image")
<\/a><\/p>\n<\/p>\nAlias<\/h3>\n<\/p>\n
Validation Parameters<\/h3>\n<\/p>\n
\n