{"id":12051,"date":"2011-11-18T00:01:00","date_gmt":"2011-11-18T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/11\/18\/use-the-powershell-passthru-parameter-and-get-back-objects\/"},"modified":"2011-11-18T00:01:00","modified_gmt":"2011-11-18T00:01:00","slug":"use-the-powershell-passthru-parameter-and-get-back-objects","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/use-the-powershell-passthru-parameter-and-get-back-objects\/","title":{"rendered":"Use the PowerShell Passthru Parameter and Get Back Objects"},"content":{"rendered":"<p><strong>Summary:<\/strong> Learn how to use the <i>passthru<\/i> parameter in Windows PowerShell to return objects from commands and allow more management tools.<\/p>\n<p>&nbsp;<\/p>\n<p><span><span><span><span><span><span><span><span><img decoding=\"async\" title=\"Hey, Scripting Guy! Question\" border=\"0\" alt=\"Hey, Scripting Guy! Question\" align=\"left\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/q-for-powertip.jpg\" width=\"34\" height=\"34\" \/><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>Hey, Scripting Guy! I have got a rather curious question that I have not been able to find anything about. What is up with the <i>passthru <\/i>parameter<i>? <\/i>I mean, I see it on some commands, and not on other commands. Also, I have no idea what it really does, but when I see it, it seems to do cool stuff. But when I try to use it, all I do is get errors. Is this some secret Microsoft trick?<\/p>\n<p>&mdash;ML<\/p>\n<p>&nbsp;<\/p>\n<p><span><span><span><span><span><span><span><span><img decoding=\"async\" title=\"Hey, Scripting Guy! Answer\" border=\"0\" alt=\"Hey, Scripting Guy! Answer\" align=\"left\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/a-for-powertip.jpg\" width=\"34\" height=\"34\" \/><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>Hello ML,<\/p>\n<p>Microsoft Scripting Guy Ed Wilson here. This is an exciting day! <a href=\"http:\/\/blogs.technet.com\/b\/heyscriptingguy\/archive\/2011\/11\/17\/learn-how-to-manage-remote-powershell-sessions.aspx\">Yesterday<\/a>, I announced that Pittsburgh will have its <a href=\"http:\/\/powershellgroup.org\/Pittsburgh.PA\">first PowerShell Users Group meeting<\/a> on December 13, 2011. Today, I get to announce that <a href=\"http:\/\/powershellgroup.org\/node\/213\">Charlotte, North Carolina, has also formed a PowerShell Users Group<\/a>. They will have their first meeting in January.<\/p>\n<p>ML, you are right, the <i>passthru <\/i>parameter seems to be mysterious. Perhaps a few examples will show how it works. First of all, <i>passthru <\/i>is not one of the common parameters, and it does not exist everywhere. The common parameters are:<\/p>\n<ul>\n<li>-Verbose<\/li>\n<li>-Debug<\/li>\n<li>-WarningAction<\/li>\n<li>-WarningVariable<\/li>\n<li>-ErrorAction<\/li>\n<li>-ErrorVariable<\/li>\n<li>-OutVariable<\/li>\n<li>-OutBuffer<\/li>\n<\/ul>\n<p>There are also two parameters that are available when a command will change system state (such as <b>Start-Process<\/b>, <b>Stop-Process<\/b>). The two risk mitigation<i> <\/i>parameters are:<\/p>\n<ul>\n<li>-WhatIf<\/li>\n<li>-Confirm<\/li>\n<\/ul>\n<p>To find all of the Windows PowerShell cmdlets that have a <i>passthru <\/i>parameter, I use the <b>Get-Command<\/b> cmdlet. I then pipe the resulting <b>cmdletInfo<\/b> object to the <b>Where-Object<\/b> and look for matches on <i>passthru.<\/i> The resulting command is shown here (in the following command, <b>gcm<\/b> is an alias for the <b>Get-Command<\/b> cmdlet; a <i>commandtype <\/i>of 8 is a cmdlet; I use the <b>?<\/b> as an alias for the <b>Where-Object<\/b> cmdlet):<\/p>\n<p style=\"padding-left: 30px\">gcm -CommandType 8 | ? {$_.definition -match &#8216;passthru&#8217;}<\/p>\n<p>When I pipe the results from this command on Windows PowerShell 2.0 with no added modules or snap-ins, it returns 44. This means that, by default, there are 44 cmdlets that use a <i>passthru <\/i>parameter.<\/p>\n<p>So, what does <i>passthru <\/i>do for me? For example, there are many Windows PowerShell cmdelts that simply work, and they do not return any data. An example is the <b>Start-Process<\/b> cmdlet. Here is an example of using the <b>Start-Process<\/b> cmdlet to start Notepad. Notice, that the line following the command is empty; this is because nothing is returned from the command:<\/p>\n<p style=\"padding-left: 30px\">PS C:\\&gt; Start-Process notepad<\/p>\n<p style=\"padding-left: 30px\">PS C:\\&gt;<\/p>\n<p>If I add the <i>passthru <\/i>switched parameter to the end of the command, a <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/system.diagnostics.process.aspx\">Process object<\/a> returns to the Windows PowerShell console. The nice thing about this is that I can use this <b>Process<\/b> object to track and work with the newly created instance of Notepad. The command to start the Notepad process and to return a <b>Process<\/b> object to the Windows PowerShell console is shown here:<\/p>\n<p style=\"padding-left: 30px\">Start-Process notepad &ndash;PassThru<\/p>\n<p>The command and associated object is shown in the following figure.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/5340.hsg-11-18-11-1.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/5340.hsg-11-18-11-1.png\" alt=\"Image of command and associated object\" title=\"Image of command and associated object\" \/><\/a><\/p>\n<p>If I store the returned <b>Process<\/b> object in a variable, I can then use it to obtain additional information about the process. In the following code, I store the returned <b>Process<\/b> object in a variable named <b>$notepad<\/b>. I then examine the start time of the process, and finally I stop the process by piping the <b>Process<\/b> object to the <b>Stop-Process<\/b> cmdlet:<\/p>\n<p style=\"padding-left: 30px\">$notepad = Start-Process notepad &ndash;PassThru<\/p>\n<p style=\"padding-left: 30px\">$notepad.StartTime<\/p>\n<p style=\"padding-left: 30px\">$notepad | Stop-Process<\/p>\n<p>The commands and associated output are shown in the following figure.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/2477.hsg-11-18-11-2.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/2477.hsg-11-18-11-2.png\" alt=\"Image of commands and associated output\" title=\"Image of commands and associated output\" \/><\/a><\/p>\n<p>Another cmdlet that contains a <i>passthru <\/i>parameter is the <b>Copy-Item<\/b> cmdlet. When I use the cmdlet to copy a file from one location to another location, nothing returns to the Windows PowerShell console. In the following command, I copy the a.txt file from the c:\\fso folder to the C:\\fso31 folder. Nothing is returned to the Windows PowerShell console:<\/p>\n<p style=\"padding-left: 30px\">Copy-Item -path C:\\fso\\a.txt -Destination C:\\fso31<\/p>\n<p>If I would like to see information about the copied file, I use the <i>passthru <\/i>switched parameter. The revised syntax is shown here:<\/p>\n<p style=\"padding-left: 30px\">Copy-Item -path C:\\fso\\a.txt -Destination C:\\fso31 &ndash;PassThru<\/p>\n<p>The command and associated output are shown in the following figure.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/5102.hsg-11-18-11-3.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/5102.hsg-11-18-11-3.png\" alt=\"Image of command and associated output\" title=\"Image of command and associated output\" \/><\/a><\/p>\n<p>The returned object is an instance of a <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/system.io.fileinfo.aspx\">FileInfo object<\/a>. To work with the file, I store the returned <b>FileInfo<\/b> object in a variable named <b>$text<\/b>. I can now directly access any of the properties of the <b>FileInfo<\/b> object. My favorite property is the <b>FullName<\/b><i> <\/i>property that points to the complete file name as well as the path to the file. Once I am finished working with the file, I can easily remote it by piping the <b>FileInfo<\/b> object stored in the <b>$Text<\/b> variable. These commands are shown here:<\/p>\n<p style=\"padding-left: 30px\">$Text = Copy-Item -path C:\\fso\\a.txt -Destination C:\\fso31 -PassThru<\/p>\n<p style=\"padding-left: 30px\">$text.GetType()<\/p>\n<p style=\"padding-left: 30px\">$text.FullName<\/p>\n<p style=\"padding-left: 30px\">$text | Remove-Item<\/p>\n<p>The commands and associated output are shown in the following figure.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/3583.hsg-11-18-11-4.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/3583.hsg-11-18-11-4.png\" alt=\"Image of commands and associated output\" title=\"Image of commands and associated output\" \/><\/a><\/p>\n<p>By default, when using the <b>Import-Module<\/b> cmdlet to import a module into the current Windows PowerShell session, nothing is returned. In the following example, I import my <a href=\"http:\/\/gallery.technet.microsoft.com\/scriptcenter\/d8a15c95-d6d2-4da9-874a-58d67f7be520\">Unit Conversion Module<\/a>; nothing appears on the Windows PowerShell console line:<\/p>\n<p style=\"padding-left: 30px\">PS C:\\&gt; Import-Module conv*<\/p>\n<p style=\"padding-left: 30px\">PS C:\\&gt;<\/p>\n<p>Now, I will remove the unit conversion module, and try it again. This time, I will use the <i>passthru <\/i>parameter. The revised command results in a <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/dd144556(VS.85).aspx\">PSModuleInfo object<\/a> returned to the Windows PowerShell console. This is useful because it tells the name of the module imported, and it lists the commands exported via the module. The commands and associated output are shown in the following figure.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/1018.Hsg-11-18-11-5.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/wp-content\/uploads\/sites\/29\/2019\/02\/1018.Hsg-11-18-11-5.png\" alt=\"Image of commands and associated output\" title=\"Image of commands and associated output\" \/><\/a><\/p>\n<p>&nbsp;<\/p>\n<p>Well, ML, as you can see, using the <i>passthru <\/i>parameter forces Windows PowerShell to go ahead and pass newly created or modified objects instead of hiding them. By knowing when to use and not to use the parameter, great flexibility is gained.<\/p>\n<p>That is all there is to using the <i>passthru <\/i>parameter. Join me tomorrow for more cool stuff about Windows PowerShell.<\/p>\n<p>I invite you to follow me on <a href=\"http:\/\/bit.ly\/scriptingguystwitter\" target=\"_blank\">Twitter<\/a> and <a href=\"http:\/\/bit.ly\/scriptingguysfacebook\">Facebook<\/a>. If you have any questions, send email to me at <a href=\"mailto:scripter@microsoft.com\" target=\"_blank\">scripter@microsoft.com<\/a>, or post your questions on the <a href=\"http:\/\/bit.ly\/scriptingforum\" target=\"_blank\">Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n<p>&nbsp;<\/p>\n<p><b>Ed Wilson, Microsoft Scripting Guy<\/b><\/p>\n<p><b>&nbsp;<\/b><\/p>\n<\/p>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Summary: Learn how to use the passthru parameter in Windows PowerShell to return objects from commands and allow more management tools. &nbsp; Hey, Scripting Guy! I have got a rather curious question that I have not been able to find anything about. What is up with the passthru parameter? I mean, I see it on [&hellip;]<\/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":[51,3,4,45],"class_list":["post-12051","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-getting-started","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell"],"acf":[],"blog_post_summary":"<p>Summary: Learn how to use the passthru parameter in Windows PowerShell to return objects from commands and allow more management tools. &nbsp; Hey, Scripting Guy! I have got a rather curious question that I have not been able to find anything about. What is up with the passthru parameter? I mean, I see it on [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/12051","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=12051"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/12051\/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=12051"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=12051"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=12051"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}