Advanced Windows PowerShell Scripting Video Training

Advanced Windows PowerShell Scripting Video Training
Advanced Windows PowerShell Scripting Video Training

Tuesday, September 20, 2016

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

No comments: