Advanced Windows PowerShell Scripting Video Training

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

Wednesday, January 2, 2013

How to pipe data to cmdlets who’s parameters do not accept input via the PowerShell pipeline.

The PowerShell pipeline is one of the key features of PowerShell that allows you to greatly reduce the script code that you need to write to accomplish your goals.  Unfortunately, not all parameters in a cmdlet allow you to feed them data via the PowerShell pipeline. Here is an example.
The Active Directory module has a cmdlet called Add-ADGroupMember.  This cmdlets intended purpose is to add an object, such as a user, to a group in active directory.  The Members parameter is used to add an object to the group.  Here is the help file for this parameter:
PS C:\> get-help Add-ADGroupMember -Parameter Members

-Members <ADPrincipal[]>
    Specifies a set of user, group, and computer objects in a comma-separated
    list to add to a group. To identify each object, use one of the following
    property values. Note: The identifier in parentheses is the LDAP display
    name.
   
      Distinguished Name
        Example:  CN=SaraDavis,CN=Europe,CN=Users,DC=corp,DC=contoso,DC=com
      GUID (objectGUID)
        Example: 599c3d2e-f72d-4d20-8a88-030d99495f20
      Security Identifier (objectSid)
        Example: S-1-5-21-3165297888-301567370-576410423-1103
      SAM Account Name (sAMAccountName)
        Example: saradavis
   
    You can also provide objects to this parameter directly.
   
    The following examples show how to specify this parameter.
   
    This example specifies a user and group to add by specifying the
    distinguished name and the SAM Account Name properties.
      -Members "CN=SaraDavis,CN=employees,CN=Users,DC=contoso,DC=com",
    "saradavisreports"
   
    This example specifies a user and a group object that are defined in the
    current Windows PowerShell session as input for the parameter.
   
      -Members $userObject, $groupObject
   
    The objects specified for this parameter are processed as
    Microsoft.ActiveDirectory.Management.ADPrincipal objects. Derived types,
    such as the following are also received by this parameter.
      Microsoft.ActiveDirectory.Management.ADUser
      Microsoft.ActiveDirectory.Management.ADComputer
      Microsoft.ActiveDirectory.Management.ADServiceAccount
      Microsoft.ActiveDirectory.Management.ADGroup
   
    You cannot pass objects through the pipeline to this parameter.
   
    Required?                    true
    Position?                    2
    Default value               
    Accept pipeline input?       false
    Accept wildcard characters?  false
   

There are two areas to take note of.  First take a look at the second to last line.  Accept pipeline input?   false.  This tells us that we can not pipe user objects to this cmdlet and have them added to the group.  The second is at the top.  This parameter will use one of four different properties to identify the object that you want to make a part of this group:
  • Distinguished Name
  • GUID
  • Security Identifier (SID)
  • SAM Account Name
We will need to provide the cmdlet one of those four from our user object.  Here is the code to do so.
Get-ADUser -Filter 'Name -like "a*"' |
 ForEach-Object {
 Add-ADGroupMember -Identity "IT" -Members $_.SAMAccountName}
First we need to pipe in a set of either user of computer objects to be added to the group.  In this case, I am adding all users whose name starts with an A.  We pipe these objects from the Get-ADUser cmdlet to ForEach-Object.  We need to do this to allow us to provide a value to the Members parameter.  Inside the ForEach-Object script block, provide the Add-ADGroupMember cmdlet.  Set the Identity parameter to the name of the group you are adding objects to.  For the Members parameter, we need to select one of the 4 properties that the Members parameter accepts.  In the example above, I am using the SAMAccountName.  The $_ represents the current object in the pipeline.  $_.SAMAccountName is the SAM Account Name of the current object.  Each time a user object is passed to the ForEach-Object cmdlet, it will add that object to the group.
You can use this method for many cmdlets with parameters that do not accept input via the PowerShell pipeline.  Do your research to understand how to provide the information to the parameters in question or you will have run time errors.

No comments: