This is post 6 of 7 in this series.
When we pass information ByPropertyName, we maintain very
good control of what parameters our information binds to. With ByValue, if you
sent a string of text, the information presented to the receiving cmdlet is
whatever the text was. With
ByPropertyName, the properties of the object are examined.
Let’s take a look at the help file for New-SMBShare. I’m only going
to show the parameters that accept pipeline input ByPropertyName.
-Name
Specifies a
name for the new SMB share. The name may be composed of any valid
file name
characters, but must be less than 80 characters in length. The names
pipe and
mailslot are reserved for use by the computer.
Required? true
Position? 2
Default
value
Accept pipeline
input? True (ByPropertyName)
Accept wildcard
characters? false
-Path
Specifies the
path to the location of the folder to share. The path must be fully
qualified;
relative paths or paths that contain wildcard characters are not
permitted.
Required? true
Position? 3
Default
value
Accept pipeline
input? True (ByPropertyName)
Accept wildcard
characters? false
-ScopeName
Specifies the
scope name of the share.
Required? false
Position? 4
Default
value
Accept pipeline
input? True (ByPropertyName)
Accept wildcard
characters? false
What the help file is telling us is that if we have an object
with a Name property containing
string data, that data will bind to the –Name
parameter of New-SMBShare. The same
if the object has a property called Path
and Scope. Here are the rules for passing parameters
ByPropertyName
- Does the object in the pipeline have property names that match the parameter names of the receiving cmdlet?
- Do those matching parameters accept pipeline input ByPropertyName?
- Do the property and parameter datatypes match?
Let’s create an object that has two properties. One called Name and the other called Path. Both will contain string data.
$Obj = New-Object -TypeName PSObject -Property
@{
Name = "MySMBShare"
Path= "C:\PS"
}
To see the contents of this object, just ask for the
variable $Obj.
PS C:\> $Obj
Name Path
---- ----
MySMBShare C:\PS
We have satisfied the requirement of having an object that
contains the same name and data types as the parameters of New-SMBShare that can accept pipeline input ByPropertyName.
Here is a look at my current SMB shares
PS C:\> Get-SmbShare
Name ScopeName
Path
Description
---- ---------
----
-----------
ADMIN$ *
C:\WINDOWS
Remote Admin
C$ * C:\ Default share
D$ * D:\ Default
share
E$ * E:\ Default
share
IPC$ *
Remote IPC
print$ * C:\WINDOWS\system32\spool\drivers
Printer Drivers
Now we are going to pipe our object to New-SMBShare
PS C:\> $Obj | New-SMBShare
Name ScopeName
Path Description
---- ---------
---- -----------
MySMBShare *
C:\PS
Let’s take a look at my SMB shares now.
PS C:\> Get-SmbShare
Name ScopeName
Path
Description
---- ---------
----
-----------
ADMIN$ * C:\WINDOWS Remote Admin
C$ * C:\ Default
share
D$ * D:\ Default
share
E$ * E:\ Default
share
IPC$ * Remote IPC
MySMBShare *
C:\PS
print$ * C:\WINDOWS\system32\spool\drivers
Printer Drivers
The graphic below shows how the properties of the object are passed to the parameters of New-SMBShare ByPropertyName. The –Scope
parameter of New-SMBShare did not
have a corresponding property in the object so its value is NULL.
This is what this command would look like without using the
PowerShell pipeline.
PS C:\> New-SMBShare -Name MySMBShare -Path C:\PS
Name ScopeName
Path Description
---- ---------
---- -----------
MySMBShare *
C:\PS
Comments