Hey, Scripting Guy! How Can I Create Organizational Units with Windows PowerShell?


(Note  Today’s response is taken from Ed Wilson’s book, Windows PowerShell Step by Step, which is available on Microsoft Press.)

Image of Windows PowerShell Step by Step book

Hey, Scripting Guy! Question

Hey, Scripting Guy! At my company, we are often called upon to create objects in Active Directory. I do not mind using the Active Directory Users and Computers tool. It’s kind of fun to use. We have to create users and groups primarily, but occasionally we need to create organizational units as well. It seems lately that we have been hiring quite a bit (please do not print our company name because our HR department is already swamped), and I am falling behind with my work. I think I am going to need to create several organizational units in the near future, and I would like to use Windows PowerShell to do this. I have looked, but do not see a cmdlet that will let me do this. Is this even possible? Please look into this, and let me know what you are able to find.

— JS


Hey, Scripting Guy! Answer

Hello JS,

It did not take me much looking into the situation because I already knew the answer. Yes, you can create organizational units with Windows PowerShell. Because there is not a cmdlet that does this (in Windows PowerShell 1.0 using Windows Server 2008 or Windows Server 2003 for your Active Directory Domain Controller) does not mean you are unable to do this. There are even cmdlets that are available from Quest Softwareone of the 2009 Summer Scripting Games sponsorsthat would allow you to do this. I am going to show you how to do this with no dependency on additional software.

The CreateOU.ps1 script will allow you to create an organizational unit named MyTestOU in a domain that is named nwtraders.msft. If this matches your needs exactly, you will be able to run the script without modification. If on the other hand, you do not work for NWTraders, you will have to modify it to suit your environment. The complete CreateOU.ps1 script is seen here.


$strCLass = “organizationalUnit”

$StrOUName = “ou=MyTestOU”

$objADSI = [ADSI]”LDAP://dc=nwtraders,dc=msft”

$objOU = $objADSI.create($strCLass, $StrOUName)


The process of creating an OU in Active Directory (AD) will provide the basis for creating other objects in AD because the technique is basically the same. The key to effectively using Windows PowerShell to create objects in Active Directory lies in using the [ADSI] accelerator. Here’s what you do: 

·         Choose the appropriate provider.

·         Use the [ADSI] accelerator.

·         Use the appropriate ADSI provider.

·         Specify the path to the appropriate object in Active Directory.

·         Use the SetInfo() method to write the changes.

The CreateOU.ps1 script illustrates each of the steps required to create an object by using ADSI. The variable $strClass is used to hold the class of object to create in Active Directory. For this script, we will be creating an organizational unit. We could just as easily create a user or a computer—as we will see shortly. We use the variable $strOUName to hold the name of the organizational unit we are going to create. For the CreateOU.PS1 script, we are going to create an OU called myTestOU. Because we will pass this variable directly to the create command, it is important we use the form shown here:


The attribute that is used to create an object in Active directory is called the relative distinguished name. Standard attribute types are expected by ADSI—such as “ou” for organizational unit. The next line of code in the CreateOU.PS1 script makes the actual connection into Active Directory. To do this, we use the [ADSI] accelerator, which wants to be given the exact path to your connection point in Active Directory (or some other directory as we will see shortly) and the name of the ADSI provider. The target of the ADSI operation is called the ADsPath.

In the CreateOU.PS1 script, we are connecting to the root of the nwtraders.msft domain and we are using the LDAP provider. The other providers we can use with ADSI are shown in Table 1. After we make our connection to Active Directory, we hold the system.DirectoryServices.DirectoryEntry object in the $objADSI variable.

Armed with the connection to Active Directory, we can now use the create method to create our new object.  The system.DirectoryServices.DirectoryEntry object that is returned is held in the $objOU variable. We use this object on the last line of the script to call the setinfo() method to write the new object into the Active Directory database.

Table 1 lists four providers available to users of ADSI. Connecting to a Microsoft Windows NT 4 system requires using the special WinNT provider. During Active Directory migrations, consultants often write a script that copies users from a Windows NT 4 domain to a Microsoft Windows Server 2003 Active Directory organizational unit or domain. In some situations (such as with customized naming schemes), writing a script is easier than using the Active Directory Migration Tool (ADMT).

Table 1  ADSI Supported Providers




To communicate with Windows NT 4.0 Primary Domain Controllers (PDCs) and Backup Domain Controllers (BDCs), and with local account databases for Windows 2000 and newer workstations.


To communicate with LDAP servers, including Exchange 5.x directory and Windows 2000 Active Directory.


To communicate with Novell Directory Services servers.


To communicate with Novell NetWare servers.


The first time I tried using ADSI to connect to a machine running Windows NT, I had a very frustrating experience because of the way the provider was implemented. Type the WinNT provider name exactly as shown in Table 1. It cannot be typed using all lowercase letters or all uppercase letters. All other provider names must be all uppercase letters, but the WinNT name is Pascal-cased; that is, it is partially uppercase and partially lowercase. Remembering this will save a lot of grief later. In addition, you don’t get an error message telling you that your provider name is “spelled incorrectly”—rather, the bind operation simply fails to connect.

The ADSI provider names are case sensitive. LDAP is all caps, WinNT is Pascal-cased. Keep this in mind to save lots of time in troubleshooting.

After the ADSI provider is specified, you need to identify the path to the directory target. This is where a little knowledge of Active Directory comes in handy because of the way the hierarchical naming space is structured. When connecting to an LDAP (Lightweight Directory Access Protocol) service provider, you must specify where in the LDAP database hierarchy to make the connection, because the hierarchy is a structure of the database itself and not the protocol or the provider. For instance, in the CreateOU.PS1 script you create an OU that resides off the root of the domain, which is called the MyTestOU OU. This can get confusing until you realize that the MyTestOU OU is contained in a domain that is called NWTRADERS.MSFT. It is vital, therefore, that you understand the hierarchy with which you are working. One tool you can use to make sure you understand the hierarchy of your domain is ADSI Edit.

ADSI Edit is included in the support tools on the Windows Server 2003 disk. It is in the SupportTools directory and is installed by clicking Suptools.msi. Installation requires Help and other programs to be closed. The installation takes only a couple of minutes and does not require a reboot. After the support tools are installed, you open a blank MMC console and add the ADSI Edit snap-in. After you install the snap-in, right-click the ADSI Edit icon, click Connect To, and specify your domain using the drop-down list, as illustrated here:

Image of how to specify your domain

JS, you now see it is rather easy to use Windows PowerShell to create objects in Active Directory. We will expand upon this tomorrow as Active Directory Week continues. To keep up to date on all the activities happening on the Script Center, follow us on Twitter. You can also follow us on Facebook. To interact with thousands of fellow scripters, we encourage you to participate in the Official Scripting Guys Forum. You can, of course, always drop us a line at scripter@microsoft.com. Until tomorrow, peace. 


Ed Wilson and Craig Liebendorfer, Scripting Guys



Discussion is closed.

Feedback usabilla icon