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.
- Take the object in the pipeline from the cmdlet on the left and discover its TypeName with Get-Member
- 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.
- 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