Summary: Microsoft Scripting Guy, Ed Wilson, talks about using the Windows PowerShell Active Directory module provider to modify user attributes in AD DS.
Hey, Scripting Guy! Just searching for users, or filtering for them, is not entirely all that useful. For me, I need to be able to make changes based on that search or filter. Is this easily done, or is it a real pain to do?
—DR
Hello DR,
Microsoft Scripting Guy, Ed Wilson, is here. Yesterday, I received word that my latest appearance on Blain Barton’s TechNet Radio Podcast is now live. In fact, Devon Musgrave at Microsoft Press wrote a cool blog about it. Blain and I talked about how certification literally changed our lives. The appearance was fun to do, and the discussion should be fun to listen to in addition to informational.
Check it out: Author news: Ed Wilson on how certification changed his life.
Note This is the fourth blog in a series about using the Active Directory module.
- In Playing with the AD: Drive for Fun and Profit, I provided an overview about the AD: drive and the Active Directory module.
- In Find Active Directory User Information with the PowerShell Provider, I talked about how to use the Windows PowerShell provider to find user information in Active Directory.
- In Use PowerShell to Find Non-Default User Properties in AD, I talked about how to retrieve additional properties beyond the four basic ones.
Find users that need modification
Suppose there are several users in an OU that have a specific attribute that needs to be changed. This may because of merging departments or in the case of a corporate buyout. In the following image, the office location of the user needs to be changed.
This particular task begins with finding the user, and it can be a bit frustrating. After attempting to find a user object with an office in Raleigh that resides in the Charlotte OU, I was about to give up. Then I decided to look up the user in ADSI Edit. Here is what I found out.
The property that appears as Officein ADUC is called PhysicalDeliveryOfficeName. Without a quick peek at ADSI Edit, I would never have discovered that one! So now, all is groovy.
Note I am using a PS Drive called Charlotte that is homed on the Charlotte OU. I explained how to create it in Playing with the AD: Drive for Fun and Profit.
Keep in mind that I do not use spaces with this filtering technique. Although it does not generate an error, the following command does not find any users either.
PS charlotte:\> Get-Item -Filter "physicaldeliveryofficename = Raleigh" -Path *
PS charlotte:\>
So I need to remove the spaces. The following command finds the two users I need to modify. The cool thing about using Get-Item here is that if more than one item matches the filter, it returns all matching objects. Here is the command I use.
PS charlotte:\> Get-Item -Filter "physicaldeliveryofficename=Raleigh" -Path *
Name ObjectClass DistinguishedName
---- ----------- -----------------
Regular User user CN=Regular User,ou=charlotte,dc=iammred...
Sample User user CN=Sample User,ou=charlotte,dc=iammred,...
PS charlotte:\>
Modify the user object with Set-ItemProperty
Now that I know what filter I need to use and I have verified that I can find the users that need updating, it is time to perform the actual modification. The cool thing here is that I use the Set-ItemProperty cmdlet to make the modifications. By using Set-ItemProperty, it becomes really easy to modify the users whose office changed from Raleigh to Charlotte. In fact, the command is so easy to use that it contains its own Filterparameter.
Therefore, all I need to do is to copy the filter I used with the Get-Item cmdlet and paste it into the Filterparameter. Because I am potentially going to make a bunch of changes, I decided to use the WhatIfparameter first to tell me exactly what the command will do. The following command illustrates using WhatIfand the Filterparameters with the Set-ItemProperty cmdlet to model a potential change to user objects in AD DS. The output generated by the WhatIfparameter lets me know the two users who will receive the modification.
PS charlotte:\> Set-ItemProperty -Filter "physicaldeliveryofficename=Raleigh" -Path *
-Name physicaldeliveryofficename -Value Charlotte -WhatIf
What if: Performing operation "Set" on Target "CN=Regular User,ou=charlotte,dc=iammred,dc=net".
What if: Performing operation "Set" on Target "CN=Sample User,ou=charlotte,dc=iammred,dc=net".
PS charlotte:\>
Now that I see the two users who will receive the changed office locations are the same two users I found by using the Get-Item cmdlet, I can be reasonably certain that the command will perform what I want it to do. Therefore, I use the up arrow to retrieve my previous command, and this time I erase the –WhatIfportion of the command. (I always use WhatIfat the end of a cmdlet call so that it is easy to delete when it comes time to run the actual command.) As shown here, nothing returns from running the command.
PS charlotte:\> Set-ItemProperty -Filter "physicaldeliveryofficename=Raleigh" -Path *
-Name physicaldeliveryofficename -Value Charlotte
PS charlotte:\>
I use the up arrow a couple of times and retrieve my previous Get-Item command to see if any users still have offices in Raleigh. As shown here, the command finds no users—they have all been changed.
PS charlotte:\> Get-Item -Filter "physicaldeliveryofficename=Raleigh" -Path *
PS charlotte:\>
OK. One more check…seeing is believing. Let me verify that the office is changed on one of the users I found earlier. Yep, the user office location is in fact changed from Raleigh, as shown here.
DR, that is all there is to using modifying user objects with the Windows PowerShell Active Directory provider. Active Directory Week will continue tomorrow when I will talk about further use of Windows PowerShell techniques with the Active Directory module provider.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy