{"id":7879,"date":"2014-10-06T06:00:00","date_gmt":"2014-10-06T13:00:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=7879"},"modified":"2014-10-04T13:08:18","modified_gmt":"2014-10-04T20:08:18","slug":"the-passthru-parameter-gimme-output","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2014\/10\/06\/the-passthru-parameter-gimme-output\/","title":{"rendered":"The PassThru Parameter: Gimme Output"},"content":{"rendered":"

I love to explain things in clear, simple terms. So, a few weeks ago, I tweeted a request for a Windows PowerShell concept that could use more explanation. Andy Fair (@ravensportal) from Oklahoma City asked for a clear explanation of the PassThru<\/strong> parameter. PassThru is frequently used and frequently ignored, so I\u2019m taking him up on his idea. Thanks, Andy!<\/p>\n

The PassThru parameter lets you request output from cmdlets that return no output by default. It\u2019s used most often to verify that the cmdlet did what you intended.<\/p>\n

 <\/p>\n

Using the PassThru Parameter<\/h3>\n

In Windows PowerShell, Get-* cmdlets almost always return the object that they get. New-* cmdlets typically return the objects that they create. Add-*, Format-*, Convert-*, and Update-* cmdlets sometimes return the objects that they\u2019ve changed. But many cmdlets return nothing \u2013 at least by default.<\/p>\n

For example, the Copy-Item cmdlet doesn\u2019t return anything. It just copies the object in the path to the specified destination. In this case, it copied the OutputFile.txt file to the CopyTest subdirectory.<\/p>\n

\n
    PS<\/span> C:\\> <\/span>Copy-Item<\/span><\/em> -<\/span>Path C:\\ps-test\\OutputFile.txt <\/span>-<\/span>Destination .\\CopyTest\r\n    <\/span>PS<\/span> C:\\> <\/span><\/pre>\n<\/blockquote>\n
 <\/p>\n
This is fine, because I typically don\u2019t want any noise in my scripts. But, if I want to verify that the file got to its intended destination, I need to run a Get-ChildItem or Test-Path command. Or, I can use the PassThru<\/strong> parameter of Copy-Item. In Copy-Item, the PassThru parameter returns the copied item in its new location.<\/p>\n
\n
    PS<\/span> C:\\> <\/span>Copy-Item -<\/span>Path .\\OutputFile.txt <\/span>-<\/span>Destination .\\CopyTest\\OutputFile.txt \u2013PassThru\r\n\r\n    <\/span>Directory<\/span>:<\/span> C:\\ps-test\\CopyTest\r\n\r\n    <\/span>Mode<\/span>                LastWriteTime     Length Name\r\n    <\/span>----<\/span> -------------<\/span> ------<\/span> ----<\/span>\r\n    -a<\/span>---<\/span>         2<\/span>\/<\/span>24<\/span>\/<\/span>2014<\/span>   8<\/span>:<\/span>43<\/span> PM         <\/span>20<\/span> OutputFile.txt    <\/span><\/pre>\n<\/blockquote>\n
 <\/p>\n
In a script, I can save the output to a variable and check it before I execute the next command.<\/p>\n
\n
    $file<\/span> =<\/span> Copy-Item<\/span> -Path<\/span> .\\OutputFile.txt <\/span>-Destination<\/span> .\\CopyTest\\OutputFile.txt \u2013PassThru\r\n    <\/span>if<\/span> (<\/span>$file<\/span>) { \u2026<<\/span>keep<\/span> going>\u2026 }   <\/span><\/pre>\n
-or-<\/pre>\n
    if<\/span> (<\/span>$file<\/span>.FullName \u2013<\/span>like<\/span> \u201c*CopyTest\\OutputFile.txt\u201d) { \u2026<<\/span>keep<\/span> going>\u2026. }<\/span><\/pre>\n<\/blockquote>\n
 <\/p>\n
When using the PassThru parameter of a command, be sure to check the type of the object that it returns. This information should be in the help file for the command, either in the description of the PassThru parameter or the Outputs section of the cmdlet help file.<\/p>\n
For example, the help for Copy-Item says:<\/p>\n
\u201cWhen you use the PassThru parameter, Copy-Item returns an object that represents the copied item. Otherwise, this cmdlet does not generate any output.\u201d<\/p><\/blockquote>\n
It\u2019s important to check before writing your verification code (e.g. if ($file) ), because not all cmdlets return the object that they change. For example, when the cmdlets in the Azure module (Azure Service Management) have a PassThru parameter, they return a Boolean value — $True or $False\u00a0 — that represents the success ($True) or failure ($False) of the command.<\/p>\n
For example, the Get-AzurePublishSettingsFile cmdlet\u00a0downloads an identity file, but it does not return an object that represents the file or its secure location. By default, the cmdlet returns nothing, but if you use its PassThru parameter, it returns $True or $False.<\/p>\n
\n
    $result<\/span> =<\/span> Get-AzurePublishSettingsFile<\/span>\r\n    if<\/span> (<\/span>$result<\/span>) { \u2026<<\/span>keep<\/span> going>\u2026 }<\/span><\/pre>\n<\/blockquote>\n
 <\/p>\n
Find the PassThru Parameter<\/h3>\n
To find cmdlets in your modules that have the PassThru parameter, use a command like this one. It runs a Get-Command command and saves the results in the $c variable. Then it uses the Where-Object cmdlet to find parameters with the name \u201cPassThru.\u201d If it finds a PassThru parameter, it returns the cmdlet that was saved in the $c pipeline variable. (I\u2019m running Windows PowerShell 4.0, but this command should work on 3.0 and later.)<\/p>\n
\n
Get-Command<\/span> -PipelineVariable c <\/span>|<\/span> \r\n    where<\/span> { <\/span>$_<\/span>.ParameterSets.Parameters.Name <\/span>-eq<\/span> \"PassThru\"<\/span> } <\/span>|<\/span> \r\n        ForEach-Object<\/strong><\/span> {<\/span>$c<\/span>}<\/span><\/pre>\n<\/blockquote>\n
 <\/p>\n
On my machine, it returned 48 cmdlets with the following distribution of verbs. It\u2019s really all over the place.<\/p>\n
PS C:\\>\u00a0 $pass | Group-Object -Property Verb
\nCount Name\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0Group
\n—– —-\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0—–
\n6 Add\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Add-Computer, Add-Content, Add-History, Add-Member…}
\n2 Clear\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Clear-ItemProperty, Clear-Variable}
\n1 Compare\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Compare-Object}
\n2 Copy\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Copy-Item, Copy-ItemProperty}
\n1 Disable\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Disable-PSBreakpoint}
\n1 Enable\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Enable-PSBreakpoint}
\n1 Export\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Export-Alias}
\n2 Import\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Import-Alias, Import-Module}
\n2 Invoke\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Invoke-RestMethod, Invoke-WebRequest}
\n2 Move\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Move-Item, Move-ItemProperty}
\n3 New\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{New-Alias, New-ModuleManifest, New-Variable}
\n1 Out\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Out-GridView}
\n1 Pop\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Pop-Location}
\n1 Push\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Push-Location}
\n2 Remove\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Remove-Computer, Remove-PSSnapin}
\n3 Rename\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Rename-Computer, Rename-Item, Rename-ItemProperty}
\n1 Restart\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Restart-Service}
\n1 Resume\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Resume-Service}
\n8 Set\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Set-Alias, Set-Content, Set-Item, Set-ItemProperty…}
\n1 Show\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Show-Command}
\n2 Start\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{Start-Process, Start-Service}\u00a0 <\/span><\/p><\/blockquote>\n
<\/pre>\n
 <\/p>\n
Implement the PassThru Parameter<\/h3>\n
You can also add the PassThru parameter to the scripts and functions that you write. Because PassThru doesn\u2019t take a value, its parameter type is always Switch<\/strong> or SwitchParameter<\/strong>, regardless of the type of the object that it returns. And, PassThru parameters should always be optional (not mandatory). For example, I have a little script that adds a timestamp to the file name. By default, it doesn\u2019t return any output, so I always run a Get-Item or Test-Path when it completes. Instead, I\u2019ll add a PassThru parameter. Here\u2019s the \u201cbefore\u201d version:<\/p>\n
    Param<\/span>\r\n            (\r\n                [<\/span>parameter<\/span>(Mandatory<\/span>=<\/span>$True<\/span>)]\r\n                [<\/span>String<\/span>]\r\n                <\/span>$FilePath<\/span>\r\n            )\r\n\r\n    <\/span>if<\/span> (<\/span>!<\/span>(<\/span>Test-Path<\/span> $FilePath<\/span>)) {<\/span>throw<\/span> \"Can't find file\\folder at $filepath\"<\/span>}\r\n\r\n    <\/span>$item<\/span> =<\/span> Get-Item<\/span> $FilePath<\/span>\r\n    $timestamp<\/span> =<\/span> (<\/span>Get-Date<\/span> $item<\/span>.Lastwritetime <\/span>-Format<\/span> o) <\/span>-replace<\/span> \":\"<\/span>, <\/span>\"-\"<\/span> \r\n\r\n    $newname<\/span> =<\/span> $item<\/span>.BaseName <\/span>+<\/span> \"-\"<\/span> +<\/span> $timestamp<\/span> +<\/span> $item<\/span>.Extension<\/span>\r\n    Rename-Item<\/span> -Path<\/span> $FilePath<\/span> -NewName<\/span> $newname<\/span><\/pre>\n
 <\/p>\n
Now, I\u2019ll add a PassThru parameter. It\u2019s optional and the parameter type is Switch. I also add a line of code at the end that checks the value of that PassThru parameter. Switch parameters have a Boolean ($True\/$False) value. The value is $True if the parameter is used (IsPresent) in the command and $False if it is not used.<\/p>\n
In my code, if the PassThru parameter is $True ( if ($PassThru) ), I call the Get-Item cmdlet to return the file with the new name.<\/p>\n
    Param<\/span>\r\n    (\r\n        [<\/span>parameter<\/span>(Mandatory <\/span>=<\/span> $True<\/span>)]\r\n        [<\/span>String<\/span>]\r\n        <\/span>$FilePath<\/span>,\r\n        \r\n        [<\/span>parameter<\/span>(Mandatory <\/span>=<\/span> $False<\/span>)]\r\n        [<\/span>Switch<\/span>]\r\n        <\/span>$PassThru<\/span>\r\n    )\r\n\r\n    <\/span>if<\/span> (<\/span>!<\/span>(<\/span>Test-Path<\/span> $FilePath<\/span>)) { <\/span>throw<\/span> \"Can't find file\\folder at $filepath\"<\/span><\/span> }\r\n\r\n    <\/span>$item<\/span> =<\/span> Get-Item<\/span> $FilePath<\/span><\/span>\r\n    $timestamp<\/span> =<\/span> (<\/span>Get-Date<\/span> $item<\/span>.Lastwritetime <\/span>-Format<\/span> o) <\/span>-replace<\/span> \":\"<\/span>, <\/span>\"-\"<\/span><\/span>\r\n\r\n    $newname<\/span> =<\/span> $item<\/span>.BaseName <\/span>+<\/span> \"-\"<\/span> +<\/span> $timestamp<\/span> +<\/span> $item<\/span><\/span>.Extension\r\n<\/span><\/span>    Rename-Item<\/span> -Path<\/span> $FilePath<\/span> -NewName<\/span> $newname<\/span><\/span>\r\n\r\n    if<\/span> (<\/span>$PassThru<\/span>) { <\/span>Get-Item<\/span> $newname<\/span> }<\/span><\/pre>\n
 <\/p>\n
But, wait! The Rename-Item cmdlet that I call to change the file name has a PassThru parameter that returns the item that it renamed. All I need to do is to pass the value of my PassThru parameter to the PassThru parameter of Rename-Item.<\/p>\n
Switch parameters can take a $True or $False value. Just type a colon (:) after the parameter name and then type the Boolean value. Here\u2019s the syntax:<\/p>\n
    -PassThru<\/span>:<\/span>$True<\/span>\r\n    -PassThru<\/span>:<\/span>$False<\/span><\/pre>\n
 <\/p>\n
Because my PassThru parameter also has a Boolean value, I can type the colon and then type the $PassThru parameter.<\/p>\n
So I can replace:<\/p>\n
    if<\/span> (<\/span>$PassThru<\/span>) { <\/span>Get-Item<\/span> $newname<\/span> }\r\n<\/span><\/pre>\n
… with a Rename-Item command that uses the PassThru parameter:<\/p>\n
    Rename-Item<\/span> -Path<\/span> $FilePath<\/span> -NewName<\/span> $newname<\/span> -PassThru<\/span>:<\/span>$PassThru\r\n<\/span>\r\n<\/pre>\n
This instance of reusing the PassThru parameter of Rename-Item isn\u2019t just a corner case. In almost all of my scripts and functions that have a PassThru parameter, I just reuse the PassThru parameter of the final command.<\/p>\n
 <\/p>\n
Thanks again for the question, Andy. If you\u2019d like me to explain a Windows PowerShell concept, or something that you\u2019ve seen in a forum or blog post, just let me know.<\/p>\n
June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at juneb@sapien.com<\/a> or follow her on Twitter at @juneb_get_help<\/a>.<\/i><\/p>\n","protected":false},"excerpt":{"rendered":"
I love to explain things in clear, simple terms. So, a few weeks ago, I tweeted a request for a Windows PowerShell concept that could use more explanation. Andy Fair (@ravensportal) from Oklahoma City asked for a clear explanation of the PassThru parameter. PassThru is frequently used and frequently ignored, so I\u2019m taking him up […]<\/p>\n","protected":false},"author":31,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[25],"tags":[934,28],"class_list":["post-7879","post","type-post","status-publish","format-standard","hentry","category-windows-powershell","tag-juneb","tag-powershell"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/7879","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/31"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=7879"}],"version-history":[{"count":11,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/7879\/revisions"}],"predecessor-version":[{"id":7904,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/7879\/revisions\/7904"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=7879"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=7879"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=7879"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}