Modify an Active Directory object.
Syntax
Set-ADObject [-Identity] ADObject
[-Add hashtable] [-Clear string[]] [-Description string] [-DisplayName string]
[-ProtectedFromAccidentalDeletion bool] [-Remove hashtable]
[-Replace hashtable] [-AuthType {Negotiate | Basic}]
[-Credential PSCredential] [-Partition string] [-PassThru]
[-Server string] [-Confirm] [-WhatIf] [CommonParameters]
Set-ADObject -Instance ADObject [-AuthType {Negotiate | Basic}]
[-Credential PSCredential] [-Partition string] [-PassThru]
[-Server string] [-Confirm] [-WhatIf] [CommonParameters]
Key
-Add hashtable
Specify values to add to an object property.
Use this parameter to add one or more values to a property that cannot be modified
using a cmdlet parameter. To modify an object property, you must use the LDAP display name.
Specify multiple values to a property by specifying a comma-separated list of values
and more than one property by separating them using a semicolon.
The format for this parameter is
-Add @{Attribute1LDAPDisplayName=value1, value2, ...;
Attribute2LDAPDisplayName=value1, value2, ...; AttributeNLDAPDisplayName=value1, value2, ...}
For example, to remove the value "555-222-2222" and add the values "555-222-1111" and "555-222-3333
" to Phone-Office-Other attribute (LDAP display name 'otherTelephone'), and add the value "555-222-9999" to Pho
ne-Mobile-Other (LDAP display name 'otherMobile'), set the Add and Remove parameters as follows.
-Add @{otherTelephone='555-222-1111', '555-222-3333'; otherMobile='555-222-9999' } -Remove @{otherTelephone='
555-222-2222'}
When you use the -Add, -Remove, -Replace and -Clear parameters together, the operations will be
performed in the order: Remove, then Add, then Replace, then clear.
-AuthType {Negotiate | Basic}
The authentication method to use: Negotiate (or 0), Basic (or 1)
A Secure Sockets Layer (SSL) connection is required for Basic authentication.
-Clear string[]
An array of object properties that will be cleared in the directory.
Use this parameter to clear one or more values of a property that cannot be modified
using a cmdlet parameter. To modify an object property, you must use the LDAP display name.
Modify more than one property by specifying a comma-separated list.
The format for this parameter is
-Clear Attribute1LDAPDisplayName, Attribute2LDAPDisplayName
For example, to clear the value for the Phone-Office-Other attribute
(LDAP display name 'otherTelephone') set the Clear parameter as follows.
-Clear otherTelephone
-Credential PSCredential
The user account credentials to use to perform this task.
The default credentials are those of the currently logged on user unless the
cmdlet is run from an Active Directory PowerShell provider drive.
If the cmdlet is run from such a provider drive, the account associated with the drive is the default.
Type a user name, such as "User64" or "Domain64\User64" or specify a
PSCredential object such as one generated by Get-Credential
If a user name is specified, the cmdlet will prompt for a password.
-Description string
A description of the object.
The LDAP Display Name for this property is "description".
-DisplayName string
The display name of the object.
The LDAP Display Name for this property is "displayName".
-Identity ADObject
An AD object. Most often this will be a Distinguished Name (e.g. CN=sample1,OU=demo,DC=SS64,DC=com)
The identity may also be given as a GUID.
Derived types, such as the following are also accepted:
[Microsoft.ActiveDirectory.Management.]
ADGroup,ADUser,ADComputer,ADServiceAccount,ADFineGrainedPasswordPolicy,ADDomain
The cmdlet searches the default naming context or partition to find the object.
If two or more objects are found, the cmdlet returns a non-terminating error.
The ADObject may also be passed through the pipeline or set via a variable.
-Instance ADObject
Specify a (modified copy of) an AD object to use to update the actual AD object.
When this parameter is used, any modifications made to the modified copy of
the object are also made to the corresponding AD object.
The cmdlet only updates the object properties that have changed.
The -Instance parameter can only update AD objects that have been retrieved
with Get-ADObject. Do not specify other parameters that set properties on the object.
Example
# Retrieve a local instance of the object.
$objectInstance = Get-ADObject -Identity "CN=someObject, DC=SS64,DC=com"
# Modify one or more properties of the object instance.
$objectInstance.Description = "New Description"
# Save changes
Set-ADObject -Instance $objectInstance
-Partition string
The distinguished name of an AD partition.
string must be one of the naming contexts on the current directory server.
The cmdlet searches this partition to find the object defined by the -Identity parameter.
Examples:
-Partition "CN=Configuration,DC=EUROPE,DC=TEST,DC=SS64,DC=COM"
-Partition "CN=Schema,CN=Configuration,DC=EUROPE,DC=TEST,DC=SS64,DC=COM"
In many cases, a default value will be used for -Partition if no value is specified.
-PassThru
Return the new or modified object.
By default (i.e. if -PassThru is not specified), this cmdlet does not generate any output.
-ProtectedFromAccidentalDeletion bool
Whether to prevent the object from being deleted.
When this property is set to true, you cannot delete the corresponding object
without changing the value of the property.
Possible values: $false or 0, $true or 1
-Remove hashtable
Remove values of an object property.
Use this parameter to remove one or more values of a property that cannot be modified
using a cmdlet parameter. To remove an object property, you must use the LDAP display name.
You can remove more than one property by specifying a semicolon-separated list.
The format for this parameter is
-Remove @{Attribute1LDAPDisplayName=value[]; Attribute2LDAPDisplayName=value[]}
For example, to add the values blue and green and remove the value pink from a property with a LDAP
display name of FavColors, set the Add and Remove parameters as follows.
-Add @{FavColors=Blue,Green} -Remove {FavColors=Pink}
When you use the -Add, -Remove, -Replace and -Clear parameters together, the operations will be
performed in the order: Remove, then Add, then Replace, then clear.
-Replace hashtable
Specify values for an object property that will replace the current values.
Use this parameter to replace one or more values of a property that cannot be modified
using a cmdlet parameter. To modify an object property, you must use the LDAP display name.
You can modify more than one property by specifying a comma-separated list.
The format for this parameter is
-Replace @{Attribute1LDAPDisplayName=value[], Attribute2LDAPDisplayName=value[]}
-Server string
The AD Domain Services instance to connect to, this may be a Fully qualified domain name,
NetBIOS name, Fully qualified directory server name (with or without port number)
-Confirm
Prompt for confirmation before executing the command.
-WhatIf
Describe what would happen if you executed the command without actually executing the command.
CommonParameters:
-Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer -OutVariable.
Set-ADObject modifies the properties of an AD object. Modify commonly used property values with the cmdlet parameters. Property values that are not associated with cmdlet parameters can be modified with -Add, -Replace, -Clear and -Remove.
The -Identity parameter specifies the AD object to modify. Identify an object by its distinguished name (DN) or GUID. The -Identity parameter may also be set to an object variable or an object passed through the pipeline. e.g. from Get-ADObject
The -Instance parameter provides a way to update an object by applying the changes made to a copy of the object. Retrieve a copy of an AD object with Get-ADObject, (and store it in a variable), after modifying the object use Set-ADObject to save the changes back to the original object.
Examples
Set the Description property on an object given its DistinguishedName:
PS C:\> Set-ADObject 'CN=RoadWarriors;OU=Europe;DC=SS64;DC=COM' -Description 'Travelling salespeople'
Remove the specified value from the attribute 'url' and set the value of the attribute 'description':
PS C:\> Set-ADObject "cdedd450-d3a8-4fd1-9d30-5ce72d64a064" -Remove @{url="www.SS64.com"} -Replace @{description="Party Manager"}
“Use what talent you possess: the woods would be very silent if no birds sang except those that sang best” ~ Henry Van Dyke
Related PowerShell Cmdlets:
Get-adObject - Get one or more AD objects.
Move-adObject - Move an AD object or container to a different container or domain.
New-adObject - Create an AD object.
Remove-adObject - Remove an AD object.
Rename-adObject - Change the name of an AD object.
Restore-adObject - Restore an AD object.