Skip to main content

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 



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.