Advanced Windows PowerShell Scripting Video Training

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

Friday, September 23, 2016

ByPropertyName: The Good Stuff

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
  1. Does the object in the pipeline have property names that match the parameter names of the receiving cmdlet?
  2. Do those matching parameters accept pipeline input ByPropertyName?
  3. 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 



No comments: