Updating Multi-Valued Active Directory Properties Part 1

Yesterday on Twitter, I got a tweet from @Docsmooth regarding how to update a multivalued property in Active Directory. There are a number of ways to handle this, especially from PowerShell naturally, so I tweeted one way in a series of tweets. But that's a hard way to learn something, and anyone jumping in the middle of the tweet stream might have been a bit confused. So I thought I'd write up a more formal explanation. Because there are a few ways to handle this situation, I'll cover each approach in a separate article. Today we'll look at using ADSI in PowerShell.

If you don't have an Active Directory cmdlet solution available (I'll cover those separately), you can still use ADSI to retrieve an object and modify it. So the first step is to get the object. The easiest way, relatively speaking, is to create an object using the [ADSI] type accelerator. All you need is the object's distinguished name.

[cc lang="PowerShell"]
PS C:\> [ADSI]$roy="LDAP://CN=Roy G. Biv,OU=Executive,OU=Employees,DC=jdhlab,DC=local"
PS C:\> $roy

distinguishedName : {CN=Roy G. Biv,OU=Executive,OU=Employees,DC=jdhlab,DC=local}
Path : LDAP://CN=Roy G. Biv,OU=Executive,OU=Employees,DC=jdhlab,DC=local
[/cc]

THe type accelerator, [adsi], is not case-sensitive, but the ADSI moniker LDAP, is. I'm telling PowerShell, "Get the LDAP path for this object in Active Directory, and turn it into a System.DirectoryServices.DirectoryEntry object." Don't worry about this last part; just know that this is an Active Directory object. Which means I can look at properties:

[cc lang="PowerShell"]
PS C:\> $roy.title
Manager
[/cc]

For simple properties like Title all you need is to simply assign a value and commit the change to the directory service by invoking the SetInfo() method.

[cc lang="PowerShell"]
PS C:\> $roy.title="Senior Manager"
PS C:\> $roy.Setinfo()
[/cc]

The more formal, ADSI approach is to use the Put() method.

[cc lang="PowerShell"]
PS C:\> $roy.put("title","Regional VP")
PS C:\> $roy.setinfo()
[/cc]

But now we get to the tricky part. Consider the otherTelephone attribute, which allows you to have a collection of phone numbers. Roy has one entry right now.

[cc lang="PowerShell"]
PS C:\> $roy.otherTelephone
555-1111
[/cc]

If I try to add a new number using Put(), I run into a problem.

[cc lang="PowerShell"]
PS C:\> $roy.put("otherTelephone","555-1112")
PS C:\> $roy.refreshcache()
PS C:\> $roy.otherTelephone
555-1111
[/cc]

The value doesn't change because this is a multivalued attribute. In these situations we need to use the PutEx() method. This method requires 3 parameters. First, an integer that indicates what type of operation you wish to carry out: 1 is Clear, 2 is Update, and 3 is Append. The second parameter is the attribute name, and the last value is an explicit array of new values. With this information, I can update the account with an additional phone number.

[cc lang="PowerShell"]
PS C:\> $roy.putex(3,"othertelephone",@("555-1112"))
PS C:\> $roy.setinfo()
PS C:\> $roy.otherTelephone
555-1112
555-1111
[/cc]

Using the Update value will keep whatever you pass as the array.

[cc lang="PowerShell"]
PS C:\> $roy.putex(2,"othertelephone",@("555-1112"))
PS C:\> $roy.setinfo()
PS C:\> $roy.refreshcache()
PS C:\> $roy.otherTelephone
555-1112
[/cc]

And to clear the entire attribute use a 0 instead of an empty array.

[cc lang="PowerShell"]
PS C:\> $roy.putex(1,"othertelephone",0)
PS C:\> $roy.refreshcache()
PS C:\> $roy.otherTelephone
PS C:\>
[/cc]

I'm going to back one more time and add the phone numbers back.

[cc lang="PowerShell"]
PS C:\> $phone=@("555-1111","555-1112","555-1113")
PS C:\> $roy.putex(3,"othertelephone",$phone)
PS C:\> $roy.setinfo()
PS C:\> $roy.refreshcache()
PS C:\> $roy.otherTelephone
555-1113
555-1112
555-1111
[/cc]

There's nothing wrong with using ADSI, and if you come from a VBScript background much of this probably looks familiar. But using a cmdlet is much easier, and I'll discuss that in a future post.

---

---