UserPrincipal Constructor (PrincipalContext) (System.DirectoryServices.AccountManagement)

MSDN Library
.NET Development
.NET Framework 3.5
.NET Framework Class Library
System.DirectoryServices.AccountManagement Namespace
UserPrincipal Class
UserPrincipal Constructor

UserPrincipal Constructor (PrincipalContext)

UserPrincipal Constructor (PrincipalContext, String, String, Boolean)

UserPrincipal Constructor (PrincipalContext)
This page is specific to:.NET Framework Version:3.54.0

.NET Framework Class Library

UserPrincipal Constructor (PrincipalContext)

Initializes a new instance of the UserPrincipal class by using the specified context.

Namespace: System.DirectoryServices.AccountManagement
Assembly: System.DirectoryServices.AccountManagement (in System.DirectoryServices.AccountManagement.dll)

Syntax

C++

JScript

Copy to Clipboard Print

'Usage

Dim context As PrincipalContext

Dim instance As New UserPrincipal(context)

'Declaration

Public Sub New ( _
    context As PrincipalContext _
)

Parameters

context: Type: System.DirectoryServices.AccountManagement..::.PrincipalContext
The PrincipalContext that specifies the server or domain against which operations are performed.

Remarks

The user principal account is not persisted when it is created. To save the account, call the Save method.

Examples

The following code example connects to the LDAP domain "fabrikam.com" with the username and password initialized in the PrincipalContext constructor to "administrator" and "securelyStoredPassword."

The properties set in the example, such as user name and e-mail address, are created under the container specified in the PrincipalContext constructor: "CN=Users,DC=fabrikam,DC=com."

PrincipalContext ctx = new PrincipalContext(
                                         ContextType.Domain,
                                         "fabrikam.com", 
                                         "CN=Users,DC=fabrikam,DC=com",
                                         "administrator", 
                                         "securelyStoredPassword"); 

UserPrincipal usr = new UserPrincipal(ctx);

usr.Name = "Jim Daly";
usr.Description = "This is the user account for Jim Daly";
usr.EmailAddress = "jimdaly@fabrikam.com";
usr.SetPassword("securelyStoredPassword");
usr.Save();

usr.Dispose();
ctx.Dispose();

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.5

Reference

UserPrincipal Class

UserPrincipal Members

UserPrincipal Overload

System.DirectoryServices.AccountManagement Namespace

System.DirectoryServices.AccountManagement

Other Resources

System.DirectoryServices.AccountManagement Namespace Overview

Community Content

Using PowerShell

Added by:Richard Siddaway MVP

This is very useful functionality to access via PowerShell. It makes user creation via scripts very much easier the system.directoryservices.directoryentry. This example was created on a Windows Server 2008 domain controller using PowerShell V2 CTP 2

Before we can do anything we need to create a user account. If you are doing this on a Vista or Windows Server 2008 with UAC enabled then you need to start PowerShell using the "Run as Administrator" option.

#requires -Version 2.0

## add the assembly
Add-Type -AssemblyName System.DirectoryServices.AccountManagement

## create a password
$password = Read-Host "Password" -AsSecureString

## create the context i.e. connect to the domain
$ctype = [System.DirectoryServices.AccountManagement.ContextType]::Domain
$context = New-Object -TypeName System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList $ctype, "manticore.org", "OU=AMTest,DC=Manticore,DC=org"

## create the user object
$usr = New-Object -TypeName System.DirectoryServices.AccountManagement.UserPrincipal -ArgumentList $context

## set the properties
$usr.Name = "AM Test1"
$usr.DisplayName = "AM Test1"
$usr.GivenName = "AM"
$usr.SurName = "Test1"
$usr.SamAccountName = "AMTest1"
$usr.UserPrincipalName = "amtest1@manticore.org"

$usr.PasswordNotRequired = $false
$usr.SetPassword($password)
$usr.Enabled = $true

## save the user
$usr.Save()

First action is to load the assembly containing the System.DirectoryServices.AccountManagement classes. This is necessary as its a .NET 3.5 assembly which isn't loaded by default into PowerShell. I've used Add-Type (new to CTP2) for this. The same task could be done with Resolve-Assembly from the PowerShell Community Extensions or by the .NET [reflection.assembly]::LoadWithPartialName() method.

We will need to set a password for our new user so we use Read-Host to get the password as a secure string - all nice and encrypted.

Before we can actually create a user account we need to create a context - i.e. connect to the domain. The arguments tell the system that we are connecting to an AD domain, the name of the domain and in which OU in the domain we want to create the account. There is an assumption here that the current user credentials are sufficient to perform the creation. If they aren't we can add a userid and password as further arguments.

Once we have the context we use System.DirectoryServices.AccountManagement.UserPrincipal with the context as an argument to create the account. It is a simple matter to then populate the properties of the account as shown. If you look at the documentation for this class you will see that there are a very limited set of properties exposed for these objects. I do like the way we can just use $usr.Enabled = $true and avoid the useraccountcontrol flags entirely. Once the properties are set save() is used to write the account information into AD.

If you need to work with any of the properties not exposed through this class e.g. the address properties then

$u = $usr.GetUnderlyingObject()

will return a DirectoryEntry() object with which we can control everything.

Creating a local user

Added by:Richard Siddaway MVP

Creating a local user is similar to creating a domain user I showed above

#requires -Version 2.0

## add the assembly
Add-Type -AssemblyName System.DirectoryServices.AccountManagement

## create a password
$password = Read-Host "Password" -AsSecureString

## create the context i.e. connect to the domain
$ctype = [System.DirectoryServices.AccountManagement.ContextType]::Machine
$context = New-Object -TypeName System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList $ctype, "your_machine_name"

## create the user object
$usr = New-Object -TypeName System.DirectoryServices.AccountManagement.UserPrincipal -ArgumentList $context

## set the properties
$usr.SamAccountName = "Newuser1"
$usr.SetPassword($password)
$usr.DisplayName = "New User"
$usr.Enabled = $true
$usr.ExpirePasswordNow()

## save the user
$usr.Save()

The main differences are:

use Machine instead of Domain for the context type
give the machine name for the context rather than the domain and OU

Everything else works as before. Notice ExpirePasswordNow() - this forces a password change when the user logs on