{"id":11961,"date":"2011-11-27T00:01:00","date_gmt":"2011-11-27T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/11\/27\/modify-a-powershell-script-to-accept-piped-input\/"},"modified":"2011-11-27T00:01:00","modified_gmt":"2011-11-27T00:01:00","slug":"modify-a-powershell-script-to-accept-piped-input","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/modify-a-powershell-script-to-accept-piped-input\/","title":{"rendered":"Modify a PowerShell Script to Accept Piped Input"},"content":{"rendered":"

Summary<\/b>: Learn how to modify a Windows PowerShell script and turn it into an advanced function that accepts piped input and has complete Help.<\/p>\n

Microsoft Scripting Guy, Ed Wilson, is here. Some things end up being way more complicated than they might appear at first glance. Today’s script is a case in point. I decided I wanted to change <\/span>the script from yesterday<\/a>, and put it into a function to make it more portable.<\/span><\/h2>\n

I also decided to add a few other features. I ended up spending the entire day working on the script. Of course, there was a meeting (I had to record the TechNet Radio pod cast. You can find it on the Scripting with Windows PowerShell<\/a> site, just below PowerShell Quiz). The complete script<\/a> appears in the Script Center Script Repository.<\/p>\n

The first thing I did was use the Function<\/b> <\/i>keyword—I specified a name and opened a pair of curly brackets (script block). I then added comment-based Help by using my Add-Help<\/b> function from my way cool Windows PowerShell ISE profile<\/a>. This portion of the script is shown here.<\/p>\n

Function Get-ShareUsers<\/b><\/p>\n

{<\/p>\n

  <#<\/p>\n

   .Synopsis<\/p>\n

    This returns user name and sid of people with permission to a share<\/p>\n

   .Description<\/p>\n

    This function returns user name and sid of users with permission to<\/p>\n

    a share. It works locally or remotely, and accepts alternate credentials<\/p>\n

    for remote connections<\/p>\n

   .Example<\/p>\n

    “data” | Get-ShareUsers<\/p>\n

    Returns information about who has access to the data share on the<\/p>\n

    local computer<\/p>\n

   .Example<\/p>\n

    “data”,”shared” | Get-ShareUsers -cn hyperv1 -credential administrator<\/p>\n

    Prompts for credentials of administrator on a remote server named hyperv1<\/p>\n

    and returns users with permissions on the shared and the data shares<\/p>\n

   .Example<\/p>\n

    $shares = @()<\/p>\n

    gwmi win32_share -cn hyperv1 -cred (Get-Credential) -Filter “type=0” |<\/p>\n

    % { $shares += $_.name.tostring() }<\/p>\n

    $shares | Get-ShareUsers -cn hyperv1 -cred administrator<\/p>\n

    This example queries WMI to create an array of share names on a remote server<\/p>\n

    It then pipelines that array to the Get-ShareUsers function where it connects<\/p>\n

    to a remote server named hyperv1 using administrator credentials<\/p>\n

   .Parameter Credential<\/p>\n

    The user name to use for Get-Credential when connecting remotely<\/p>\n

   .Parameter Share<\/p>\n

    The name of the share to return information about<\/p>\n

    .Parameter cn<\/p>\n

     The name of the remote computer.<\/p>\n

   .Notes<\/p>\n

    NAME:  Get-ShareUsers<\/p>\n

    AUTHOR: ed wilson, msft<\/p>\n

    LASTEDIT: 11\/22\/2011 18:04:10<\/p>\n

    KEYWORDS: Windows PowerShell, Scripting Guy!, Weekend Scripter, storage,<\/p>\n

    shared folders and mapped drives, security<\/p>\n

    HSG: WES-11-27-11<\/p>\n

   .Link<\/p>\n

     Http:\/\/www.ScriptingGuys.com<\/p>\n

 #Requires -Version 2.0<\/p>\n

 #><\/p>\n

Next, I specify that I want to use CmdletBinding<\/b>. I also make the Share <\/i>parameter mandatory, and I set it up to accept piped input. The CmdletBinding<\/b> and the parameter section of the script are shown here.<\/p>\n

[CmdletBinding()]<\/p>\n

 Param (<\/p>\n

  [string]$credential,<\/p>\n

  [Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]<\/p>\n

  [string]$share,<\/p>\n

  [string]$cn = $env:COMPUTERNAME<\/p>\n

 )<\/p>\n

In the Begin <\/i>portion of my function, I setup my splatting. I create an empty hash table named RemoteParam<\/i>, <\/i>and then I add the Credential <\/i>and the ComputerName <\/i>values to the hash table. This portion of the script is shown here.<\/p>\n

BEGIN<\/p>\n

 {<\/p>\n

  $remoteParam = @{}<\/p>\n

  if($credential) { $remoteParam.add( “Credential”, (Get-Credential $credential))<\/p>\n

                   $remoteParam.Add( “Computername”, $cn) }<\/p>\n

 }<\/p>\n

I then create the Process <\/i>portion of the function. I use the automatic variable $input<\/b> to display the current item that is piped to the function. I then use the $query<\/b> from yesterday’s script. This portion of the Process <\/i>block is shown here.<\/p>\n

PROCESS {<\/p>\n

   $input<\/p>\n

   $query = “Associators of {win32_LogicalShareSecuritySetting=’$share’}<\/p>\n

   Where resultclass = win32_sid”<\/p>\n

I modify the Get-WmiObject<\/b> command to use splatting to accept the ComputerName<\/i> and Credential<\/i> parameters. I only pass these if the Credential <\/i>parameter appears on the command line. Here is the modified Get-WmiObject<\/b> command.<\/p>\n

Get-WmiObject -query $query @RemoteParam<\/p>\n

The remainder of the function is the same as yesterday’s script; and therefore, I will not go over it. It is shown here, for the sake of completeness.<\/p>\n

Select-Object -Property @{LABEL=”User”;EXPRESSION=<\/p>\n

    {“{0}\\{1}” -f $_.ReferencedDomainName, $_.AccountName}}, SID<\/p>\n

   }<\/p>\n

} #end function Get-ShareUsers<\/p>\n

To use the Get-ShareUsers<\/b> function, I pipe a shared folder name to it. Here is an example command.<\/p>\n

“Data” | Get-ShareUsers -credential administrator -cn hyperv1<\/p>\n

The command and its associated output are shown in the following image.<\/p>\n

\"Image<\/a><\/p>\n

I can pipe an array of share names to the function. This is shown here.<\/p>\n

“shared”,”data” | Get-ShareUsers -credential administrator -cn hyperv1<\/p>\n

The command and its associated output are shown in the following image.<\/p>\n

\"Image<\/a><\/p>\n

One of the cool things to do with this function, is to use WMI to create an array of share names. Here is some code that does that.<\/p>\n

$shares = @()<\/p>\n

gwmi win32_share -cn hyperv1 -cred $cred -Filter “type=0” |<\/p>\n

% { $shares += $_.name.tostring() }<\/p>\n

When I have the shares in an array, I can pipe the array to the Get-ShareUsers<\/b> function. The syntax to do this is shown here.<\/p>\n

$shares | Get-ShareUsers -credential administrator -cn hyperv1<\/p>\n

The commands and the associated output are shown in the following image.<\/p>\n

\"Image<\/a><\/p>\n

Well, this is about all for messing around with shares and who has permissions to them. Remember, the complete script is in the Scripting Guys Script Repository<\/a>.<\/p>\n

If you are going to be in Pittsburg, Pennsylvania on December 13, 2011, you should check out the Pittsburgh PowerShell Users Group meeting<\/a>. The Scripting Wife and I will be there, and I will be speaking about Windows PowerShell Best Practices. It will be awesome!<\/p>\n

Join me tomorrow as I begin a new week on the Hey, Scripting Guy! Blog. Oh, by the way, have you noticed that now we have more Windows PowerShell articles<\/a> on the Hey, Scripting Guy! Blog than VBScript articles<\/a>? This is cool!<\/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","protected":false},"excerpt":{"rendered":"

Summary: Learn how to modify a Windows PowerShell script and turn it into an advanced function that accepts piped input and has complete Help. Microsoft Scripting Guy, Ed Wilson, is here. Some things end up being way more complicated than they might appear at first glance. Today’s script is a case in point. I decided […]<\/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":[3,63,185,12,61,45],"class_list":["post-11961","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-scripting-guy","tag-security","tag-shared-folders-and-mapped-drives","tag-storage","tag-weekend-scripter","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Learn how to modify a Windows PowerShell script and turn it into an advanced function that accepts piped input and has complete Help. Microsoft Scripting Guy, Ed Wilson, is here. Some things end up being way more complicated than they might appear at first glance. Today’s script is a case in point. I decided […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/11961","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=11961"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/11961\/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=11961"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=11961"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=11961"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}