Skip to main content

The PowerShell Pipeline at the Surface: ByValue

This is post 3 of 7 in this series.

In reality, we are not actually passing objects to the cmdlet on the right, rather we are passing objects to the parameters of the cmdlet on the right. There are two ways that parameter passing can be achieved; ByValue and ByPropertyName.

In ByValue parameter passing, we actually look at the value of the object.  For example, if we pass a string object to a cmdlet that can receive the object ByValue, it looks that what the string says.  In other words, if the string says “Hello World”, the cmdlet will use “Hello World”. To determine how parameter passing will work, or even if it will, we need to perform two tasks. 

Task number 1 is to discover the TypeName of the object the was created from the cmdlet on the left.  This can be accomplished in a couple of ways.  The first way is to pipe the object to the cmdlet Get-Member.

PS C:\> "Bits" | Get-Member


   TypeName: System.String

Name             MemberType            Definition                                            
----             ----------            ----------                                           
Clone            Method                System.Object Clone(), System.Object ICloneable.Clo...
CompareTo        Method                int CompareTo(System.Object value), int CompareTo(s...
Contains         Method                bool Contains(string value)              

When you do, take a look at the TypeName.  In this case, the TypeName is System.String.  We will just say that it is a string object for short.

Another way to get the TypeName is to use the GetType() method.

PS C:\> ("Bits").GetType()

IsPublic IsSerial Name                                     BaseType                       
-------- -------- ----                                     --------                        
True     True     String                                   System.Object    

Next, we need to take a look at the full help file for the cmdlet we are sending this string object to.  In our scenario, we are going to pass our string “Bits” to Get-Service.  Let’s look at the Parameter section of the help file for Get-Service.

PS C:\> Get-help Get-Service -Parameter *

-ComputerName []
    Gets the services running on the specified computers. The default is the local
    computer.
   
    Type the NetBIOS name, an IP address, or a fully qualified domain name (FQDN) of a
    remote computer. To specify the local computer, type the computer name, a dot (.), or
    localhost.
   
    This parameter does not rely on Windows PowerShell remoting. You can use the
    ComputerName parameter of Get-Service even if your computer is not configured to run
    remote commands.
   
    Required?                    false
    Position?                    named
    Default value                none
    Accept pipeline input?       true (ByPropertyName)
    Accept wildcard characters?  false
   

-DependentServices []
    Indicates that this cmdlet gets only the services that depend upon the specified
    service.
   
    By default, this cmdlet gets all services.
   
    Required?                    false
    Position?                    named
    Default value                none
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-DisplayName
    Specifies, as a string array, the display names of services to be retrieved. Wildcards
    are permitted. By default, this cmdlet gets all services on the computer.
   
    Required?                    true
    Position?                    named
    Default value                none
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-Exclude []
    Specifies, as a string array, a service or services that this cmdlet excludes from the
    operation. The value of this parameter qualifies the Name parameter. Enter a name
    element or pattern, such as "s*". Wildcards are permitted.
   
    Required?                    false
    Position?                    named
    Default value                none
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-Include []
    Specifies, as a string array, a service or services that this cmdlet includes in the
    operation. The value of this parameter qualifies the Name parameter. Enter a name
    element or pattern, such as "s*". Wildcards are permitted.
   
    Required?                    false
    Position?                    named
    Default value                none
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

-InputObject []
    Specifies ServiceController objects representing the services to be retrieved. Enter a
    variable that contains the objects, or type a command or expression that gets the
    objects. You can also pipe a service object to this cmdlet.
   
    Required?                    false
    Position?                    named
    Default value                none
    Accept pipeline input?       true (ByValue)
    Accept wildcard characters?  false
   

-Name []
    Specifies the service names of services to be retrieved. Wildcards are permitted. By
    default, this cmdlet gets all of the services on the computer.
   
    Required?                    false
    Position?                    1
    Default value                none
    Accept pipeline input?       true(ByValue,ByPropertyName)
    Accept wildcard characters?  false
   

-RequiredServices []
    Indicates that this cmdlet gets only the services that this service requires.
   
    This parameter gets the value of the ServicesDependedOn property of the service. By
    default, this cmdlet gets all services.
   
    Required?                    false
    Position?                    named
    Default value                none
    Accept pipeline input?       false
    Accept wildcard characters?  false
    

In the above help file, look at the Accept pipeline input attribute on each parameter.  Do any of them have a value of True? Two of them do.  –Name and –ComputerName both accept pipeline input.  Does one of these accept pipeline input ByValue?  Only the –Name parameter does.  As a matter of fact, it accepts input both ByValue and ByPropertyName.  When you are faced with this scenario, ByValue is always tried first.

Next, we need to look at the data type of the –Name parameter.

PS C:\> Get-Help Get-Service -Parameter Name

-Name []
    Specifies the service names of services to be retrieved. Wildcards are permitted. By
    default, this cmdlet gets all of the services on the computer.
   
    Required?                    false
    Position?                    1
    Default value                none
    Accept pipeline input?       true(ByValue,ByPropertyName)
    Accept wildcard characters?  false

Right after the parameters name, you will see the data type []. In other words, the –Name parameter of Get-Service will accepts a string object’s value if passed to it from the PowerShell pipeline.  Let’s give it a try.

PS C:\> "Bits" | Get-Service

Status   Name               DisplayName                          
------   ----               -----------                          
Running  Bits               Background Intelligent Transfer Ser...

As you can see, it works!  This is what it looks like without using the pipeline.

PS C:\> Get-Service -Name "Bits"

Status   Name               DisplayName                          
------   ----               -----------                          
Running  Bits               Background Intelligent Transfer Ser...

Here is a summary of the steps that we took to determine if an object will be accepted ByValue by another cmdlet.

  1. Take the object in the pipeline from the cmdlet on the left and discover its TypeName with Get-Member
  2. Open the full help file of the receiving cmdlet on the right and see if any of its parameters accept input from the PowerShell pipeline ByValue.
  3. If they do accept pipeline input ByValue, do they accept the same object type that you are passing to it? If so, the passing ByValue will work.


1

Comments

Popular posts from this blog

Adding a Comment to a GPO with PowerShell

As I'm writing this article, I'm also writing a customization for a PowerShell course I'm teaching next week in Phoenix.  This customization deals with Group Policy and PowerShell.  For those of you who attend my classes may already know this, but I sit their and try to ask the questions to myself that others may ask as I present the material.  I finished up my customization a few hours ago and then I realized that I did not add in how to put a comment on a GPO.  This is a feature that many Group Policy Administrators may not be aware of. This past summer I attended a presentation at TechEd on Group Policy.  One organization in the crowd had over 5,000 Group Policies.  In an environment like that, the comment section can be priceless.  I always like to write in the comment section why I created the policy so I know its purpose next week after I've completed 50 other tasks and can't remember what I did 5 minutes ago. In the Group Policy module for PowerShell V3, th

Return duplicate values from a collection with PowerShell

If you have a collection of objects and you want to remove any duplicate items, it is fairly simple. # Create a collection with duplicate values $Set1 = 1 , 1 , 2 , 2 , 3 , 4 , 5 , 6 , 7 , 1 , 2   # Remove the duplicate values. $Set1 | Select-Object -Unique 1 2 3 4 5 6 7 What if you want only the duplicate values and nothing else? # Create a collection with duplicate values $Set1 = 1 , 1 , 2 , 2 , 3 , 4 , 5 , 6 , 7 , 1 , 2   #Create a second collection with duplicate values removed. $Set2 = $Set1 | Select-Object -Unique   # Return only the duplicate values. ( Compare-Object -ReferenceObject $Set2 -DifferenceObject $Set1 ) . InputObject | Select-Object – Unique 1 2 This works with objects as well as numbers.  The first command creates a collection with 2 duplicates of both 1 and 2.   The second command creates another collection with the duplicates filtered out.  The Compare-Object cmdlet will first find items that are diffe

How to list all the AD LDS instances on a server

AD LDS allows you to provide directory services to applications that are free of the confines of Active Directory.  To list all the AD LDS instances on a server, follow this procedure: Log into the server in question Open a command prompt. Type dsdbutil and press Enter Type List Instances and press Enter . You will receive a list of the instance name, both the LDAP and SSL port numbers, the location of the database, and its status.