Summary: Learn how to use Windows PowerShell and the Active Directory cmdlets to update user objects in Active Directory.

Hey, Scripting Guy! Watching you write a custom function to search Active Directory is about as much fun as watching paint dry. One reason we upgraded to Windows Server 2008 R2 was to gain access to the Active Directory cmdlets. I am not really good at using them, but I think I should be able to use them to find users that are missing a value for a particular attribute, and then supply a default value for it. Is this possible?

— MW

Hello MW,

Microsoft Scripting Guy Ed Wilson here. Watching paint dry could be fun if I had a bag of ANZAC biscuits and a pot of Darjeeling tea. I would also want my Zune HD so that I could play some nice jazz. If I had a nice recliner chair, I could get into some paint-drying time. Still, I do not think it would be as much fun as writing Windows PowerShell scripts. The complete SetADPropertyADCmdlets.ps1 script is shown here.

SetADPropertyADCmdlets.ps1

Import-Module ActiveDirectory 
 $users = $i = $null 
 $users = Get-ADUser -SearchBase “ou=testou,dc=nwtraders,dc=com” -filter * ` 
  -property description 
 ForEach($user in $users) 
  { 
   if([string]::isNullOrEmpty($user.description)) 
    { 
      “modifying $($user.name)” 
      Set-ADUser -Identity $user.distinguishedName -Description “added via script” 
      $i++ 
    } 
 } 
“modified $i users”

Before we dive into the script, l like to take a look at my target. I seldom write a script that works with Active Directory without having ADSI Edit and Active Directory Users and Computers open. In fact, I have a custom MMC that contains both of those snap-ins as well as several other tools. The contents of the testou in the Nwtraders.com domain is shown in the following image.

As you can see in the previous image, the testou organizational unit contains both users and computers. In addition, one of the user objects contains a value for the description property; the other objects do not have a value for the description property. I only wish to add a description property value for the users that do not currently have a description; I do not wish to overwrite any existing values. In addition, the description I am going to add is not appropriate for computer objects. Sounds complicated, but it is a very common scenario. The script will need the ability to perform the following actions.

·         Search a specific organizational unit for user objects.

·         Find user objects that are missing a value for a specific attribute.

·         Write a default value for user objects that are missing a value for the specific attribute.

The first thing to do when using the Microsoft Active Directory cmdlets is to use the Import-Module cmdlet to import the ActiveDirectory module.

For information about how to obtain and use the Microsoft Active Directory cmdlets, see What’s up with Active Directory Domain Services Cmdlets?

After the ActiveDirectory module has been imported, I set the $users and the $i variables to $null. This portion of the SetADPropertyADCmdlets.ps1 script is shown here:

Import-Module ActiveDirectory

$users = $i = $null

I now use the Get-ADUser cmdlet to retrieve users from the testou in my nwtraders.com domain. The filter property is required, so I give it the wildcard character * to tell it I want everything returned. In addition, I specify that I want the description property returned in the search results. For performance reasons, the Get-ADUser cmdlet returns only a subset of the available properties from Active Directory Domain Services (AD DS). The search results are stored in the $users variable. The command is a little long, so I use line continuation backtick character (`) to move the –property description portion of the command to the second line. This is a requirement for publishing the script to the blog. In my original script, the command fit nicely on a single line; it is therefore a single logical line command. The command is shown here:

$users = Get-ADUser -SearchBase “ou=testou,dc=nwtraders,dc=com” -filter * `

   -property description

A collection is returned via the Get-ADUser cmdlet. Therefore, I use the ForEach statement to walk through the collection. Unfortunately, I cannot pipe the results of the Get-ADUser cmdlet directly to Set-ADUser. When inside the collection, I use the static isNullOrEmpty method from the system.string .NET Framework class. I have it check the description property on the user object. If the property is empty or null, I then display a string that states I am modifying the user object. This portion of the script is shown here:

ForEach($user in $users)

  {

   if([string]::isNullOrEmpty($user.description)) 

    { 

      “modifying $($user.name)”

To modify the user object, use the Set-ADUser cmdlet. The identity parameter is used to specify which b object to modify; this parameter will accept a distinguished name, the object GUID, the security identifier (SID), the SAM account name, or the name of the object. Here, I chose the distinguishedname property from the user object. The description parameter holds the value to add to the description attribute on the object. This command is shown here:

Set-ADUser -Identity $user.distinguishedName -Description “added via script”

The last two things to do are to increment the $i counter variable and display a summary string. This portion of the script is shown here:

$i++

    }

 }

“modified $i users”

When the script runs in the Windows PowerShell ISE, the output appears that is shown in the following image.

Active Directory Users and Computers is used to verify that the changes were completed. Keep in mind that you might need to hit refresh (F5) a few times before the changes appear. In addition, depending on your network topology, it might actually take a minute or two. On my system, the changes shown in the following image took a few seconds of pressing refresh before they appeared.

MW, that is all there is to using the Microsoft Active Directory cmdlets to find objects with missing values and then assign default values to those objects. Active Directory Week draws to an end. Join us tomorrow when we will have a guest blogger talk about the Windows PowerShell Scripting Community. You should not miss this excellent article.  

We invite you to follow us on Twitter and Facebook. If you have any questions, send email to us at scripter@microsoft.com, or post them on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson and Craig Liebendorfer, Scripting Guys