Active Directory Powershell: The Drive is the connection

People familiar with LDAP, ADSI or third party Active Directory Powershell cmdlets might be wondering where are the cmdlets for making and closing a connection?

The answer is: connection lifecycle is automatically managed by AD cmdlets. If you want the cmdlet to target a specific server then use the -server parameter and provide "servername:portnum" value, otherwise the cmdlets will attempt to find a suitable DC and establish a connection. The connection is closed by the cmdlet before exiting. Example:

PS C:\> Get-ADUser -Server "" -credential "\administrator" -filter { objectClass -like "*" } -SearchBase "OU=Accounts Department,DC=fabrikam,DC=com"

Good .. huh? But wait, there is a caveat here. When using the above method, a new connection will be opened and closed for each cmdlet invocation. This is ok for one or two operations but is very inefficient for bulk operations. So how can you share a single connection across multiple cmdlet invocations?

The answer is: create an Active Directory PSDrive and run the cmdlets under the drive's context. The Active Directory PSDrive maintains a live connection to the specified/discovered server and it will be reused by all the cmdlets running under its context. The drive also maintains the lifecycle of the connection, so if the connection gets closed due to timeout or some other reason, then a new connection is created underneath.

Here is an example to create a new drive connected to a Global catalog (GC) server in a domain:

PS C:\> New-PSDrive -PSProvider ActiveDirectory -Name GC -Root "" -Server ""

Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
GC                                     ActiveDire...

PS D:\> cd GC:
PS GC:\>

Tips: If you provide domain name to the -server parameter instead of a DC name, then New-PSDrive would discover a DC in the specified domain and connect to it. The advantage is that if the current DC goes down for some reason then the drive would find a new suitable DC and connect to it.

New-PSDrive and all other AD cmdlets do not expose DC discovery (aka DC-Locator) options such as: GlobalCatalog, PDC etc. If you would like to connect to a DC with a specific role then you can leverage other AD cmdlets such as: Get-ADDomainController, Get-ADForest etc and use its output to specify the server.

Here is an example to create a new drive connected to PrimaryDC (PDC) using Get-ADDomainController cmdlet:

PS D:\> New-PSDrive -PSProvider ActiveDirectory -Name PdcDrive -Root "" -Server (Get-ADDomainController -Discover -Service PrimaryDC).Name
Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
PdcDrive                               ActiveDire...

Here is an example to create a new drive connected to Schema Master FSMO Owner using Get-ADForest cmdlet:

PS D:\> New-PSDrive -PSProvider ActiveDirectory -Name SchemaMasterDrive -Root "" -Server (Get-ADForest -Current LoggedOnUser).SchemaMaster

Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
SchemaM...                             ActiveDire...

To see a list of current Active Directory PSDrives loaded in your console type

PS D:\> Get-PSDrive -PSProvider ActiveDirectory

Tips: Running cmdlets under drive speeds up the cmdlet execution significantly. Our performance data shows approximately 75% performance improvement when cmdlets are run under drive.


Swaminathan Pattabiraman [MSFT]
Developer - Active Directory Powershell Team

Comments (4)

  1. Xaegr says:

    Get-ADUser -Server ""

    New-PSDrive -PSProvider ActiveDirectory -Name GC -Root "" -Server ""

    May be use separate -port parameter to specify port?

    Get-ADDomainCOntroller -Discover parameter should be on by default always. Or i missing something?

  2. People familiar with LDAP, ADSI or third party Active Directory Powershell cmdlets might be wondering

  3. Please help! says:

    New-PSDrive: A parameter cannot be found that matches parameter name 'Server'

  4. Marcin says:

    Is there a way to bind over LDAPS? Changing port to 636 doesn't do the trick.

Skip to main content