Set-GPRegistryValue
Configures one or more registry-based policy settings under either Computer Configuration or User Configuration in a GPO.
Syntax
Set-GPRegistryValue
-Guid <Guid>
-Key <String>
[-ValueName <String[]>]
[-Value <PSObject>]
[-Type <RegistryValueKind>]
[-Domain <String>]
[-Server <String>]
[-Additive]
[-Disable]
[-ValuePrefix <String>]
[-WhatIf]
[-Confirm]
[<CommonParameters>] Set-GPRegistryValue
[-Name] <String>
-Key <String>
[-ValueName <String[]>]
[-Value <PSObject>]
[-Type <RegistryValueKind>]
[-Domain <String>]
[-Server <String>]
[-Additive]
[-Disable]
[-ValuePrefix <String>]
[-WhatIf]
[-Confirm]
[<CommonParameters>] Description
The Set-GPRegistryValue cmdlet configures a registry-based policy setting under either Computer Configuration or User Configuration in a Group Policy Object (GPO). The policy setting configures keys or values in the registry on the client computer when the GPO is applied.
You can specify the GPO by name or by its GUID, or you can pipe a GPO object to the cmdlet. You can also pipe a PolicyRegistrySetting object to the cmdlet.
You can configure registry-based policy settings for:
One or more registry values by passing the Key, ValueName, Value, and Type parameters. For multiple registry values, pass a comma-separated list for both the ValueName and Value parameters. When you specify multiple registry values, only the String and ExpandString data types are supported.
A list of one or more registry values that share the same name prefix by passing the Key and Type parameters, and a single value or a comma-separated list for the Value parameter. You can optionally specify the value name prefix by using the ValuePrefix parameter. Only the String and ExpandString data types are supported for lists.
You can use the Additive parameter to ensure that existing registry values for the key are not overwritten by the new policy setting when the GPO is applied.
You can also delete registry values on a client when the GPO is applied by disabling a policy setting with the Disable parameter. You can disable:
All the registry values under a specified registry key by passing the Key parameter. No subkeys, or their values, are deleted on the client.
A single registry value by passing the Key parameter and the ValueName parameter.
Multiple registry values by passing the Key parameter and a comma-separated list for the ValueName parameter.
Examples
Example 1: Configure a registry-based policy setting for a registry value
PS C:\> Set-GPRegistryValue -Name "TestGPO" -Key "HKCU\Software\Policies\Microsoft\Windows\Control Panel\Desktop" -ValueName "ScreenSaveTimeOut" -Type DWORD -Value 900
DisplayName : TestGPO
DomainName : contoso.com
Owner : CONTOSO\Domain Admins
Id : 35c12ab3-956c-45d5-973b-46b17d225f47
GpoStatus : AllSettingsEnabled
Description :
CreationTime : 2/24/2009 4:41:03 PM
ModificationTime : 2/25/2009 12:42:00 PM
UserVersion : AD Version: 3, SysVol Version: 3
ComputerVersion : AD Version: 34, SysVol Version: 34
WmiFilter :This command configures a registry-based policy setting for the registry value "HKCU\Software\Policies\Microsoft\Windows\Control ScreenSaverTimeOut" with a value of 900 and a data type of DWord. This policy setting sets the Screen Saver timeout to 900 seconds (15 minutes) when Group Policy is applied on the client.
Example 1: Configure a registry-based policy settings for multiple registry values
PS C:\> Set-GPRegistryValue -Name "TestGPO" -Key "HKCU\Software\Policies\Microsoft\ExampleKey" -ValueName "ValueOne", "ValueTwo", "ValueThree" -Type String -Value "String 1", "String 2", "String 3"This command configures registry-based policy settings to set three registry values. The policy settings are configured in the User Configuration section of the GPO. When the GPO is applied on the client, the following registry values are set:
"HKCU\Software\Policies\Microsoft\ExampleKey ValueOne" "String 1"
"HKCU\Software\Policies\Microsoft\ExampleKey ValueTwo" "String 2"
"HKCU\Software\Policies\Microsoft\ExampleKey ValueThree" "String 3"
Example 3: Configure a registry-based policy setting to set a list of registry values
PS C:\> Set-GPRegistryValue -Name "TestGPO" -Key "HKCU\Software\Policies\Microsoft\ExampleKey" -ValuePrefix "MyValue" -Type String -Value "String 1", "String 2", "String 3"This command configures a registry-based policy setting to set a list of three registry values. The policy settings are configured in the Computer Configuration section of the GPO. Because the Additive parameter is not specified, when the GPO is applied on the client any list values under the key are deleted -- then, the following registry values are set:
"HKCU\Software\Policies\Microsoft\ExampleKey MyValue1" "String 1"
"HKCU\Software\Policies\Microsoft\ExampleKey MyValue2" "String 2"
"HKCU\Software\Policies\Microsoft\ExampleKey MyValue3" "String 3"
If you specify the Additive parameter, the list values are added to the existing list values on the client when the GPO is applied. The actual value names assigned to the list values depends on the number of existing list values on the client.
Example 4: Disable registry-based policy settings for specific registry values
PS C:\> Set-GPRegistryValue -Disable -Name "TestGPO" -Key "HKCU\Software\Policies\Microsoft\ExampleKey" -ValueName "ValueOne", "ValueTwo", "ValueThree"This command disables the registry-based policy settings, in the User Configuration section, for the specified registry values. When the GPO is applied on the client, the registry values are deleted from the registry on the client.
Example 5: Disable registry-based policy settings for a specific registry key
PS C:\> Set-GPRegistryValue -Disable -Name "TestGPO" -Key "HKCU\Software\Policies\Microsoft\ExampleKey"This command disables the registry-based policy setting, in the User Configuration section, for the specified registry key. When the GPO is applied on the client, all first level values will be deleted from the registry key. Subkeys and their values are not modified.
Parameters
-Additive
Indicates that registry values should be appended to existing values under the key when the GPO is applied on a client.
By default, when Group Policy is processed on a client, existing values under a registry key are deleted before any new values are written to the registry. By using the Additive parameter for a registry-based policy setting, you can specify that the new value should be added to the registry key without deleting the existing values.
You cannot specify the Disable parameter with this parameter.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Disable
Indicates that the cmdlet disables the registry-based policy setting.
You can disable a policy setting for a registry key or value:
For a registry key, specify the Key parameter without the ValueName parameter. When the GPO is applied on the client, all of the values directly under the key are removed from the registry. The key itself is not removed from the registry, nor are any of its subkeys, or their values, removed.
For a registry value, specify the Key parameter together with the ValueName parameter. When the GPO is applied on the client, only the specified value is removed from the registry.
To remove a policy setting from a GPO without affecting existing registry keys or values on a client when Group Policy is processed, use the Remove-GPRegistryValue cmdlet.
You cannot specify the Additive, Type, Value, or ValuePrefix parameters with the Disable parameter.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Domain
Specifies the domain for this cmdlet. You must specify the fully qualified domain name (FQDN) of the domain.
For the Set-GPRegistryValue cmdlet, the GPO in which to configure the registry-based policy setting must exist in this domain.
If you do not specify the Domain parameter, the domain of the user that is running the current session is used. If the cmdlet is being run from a computer startup or shutdown script, the domain of the computer is used. For more information, see the Notes section in the full Help.
If you specify a domain that is different from the domain of the user that is running the current session (or, for a startup or shutdown script, the computer), a trust must exist between that domain and the domain of the user or the computer.
You can also refer to the Domain parameter by its built-in alias, domainname. For more information, see about_Aliases.
| Type: | String |
| Aliases: | DomainName |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Guid
Specifies the GPO in which to configure the registry-based policy setting by its globally unique identifier (GUID). The GUID uniquely identifies the GPO.
You can also refer to the Guid parameter by its built-in alias, id.
| Type: | Guid |
| Aliases: | Id |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Key
Specifies the registry key for the registry-based policy setting; for instance, HKLM\Software\Policies\Microsoft\Windows NT\DNSClient.
The key must be in one of the two following registry hives:
HKEY_LOCAL_MACHINE (HKLM) for a registry-based policy setting in Computer Configuration.
HKEY_CURRENT_USER (HKCU) for a registry-based policy setting in User Configuration.
You can also refer to the Key parameter by its built-in alias, FullKeyPath.
| Type: | String |
| Aliases: | FullKeyPath |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Name
Specifies the GPO in which to configure the registry-based policy setting by its display name.
The display name is not guaranteed to be unique in the domain. If another GPO with the same display name exists in the domain, an error occurs. You can use the Guid parameter to uniquely identify a GPO.
You can also refer to the Name parameter by its built-in alias, displayname.
| Type: | String |
| Aliases: | DisplayName |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Server
Specifies the name of the domain controller that this cmdlet contacts to complete the operation. You can specify either the fully qualified domain name (FQDN) or the host name.
If you do not specify the name by using the Server parameter, the primary domain controller (PDC) emulator is contacted.
You can also refer to the Server parameter by its built-in alias, dc.
| Type: | String |
| Aliases: | DC |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Type
Specifies the data type for the registry-based policy setting.
The acceptable values for this parameter are:
- String
- ExpandString
- Binary
- DWord
- MultiString
- QWord
For more information about these data types, see Microsoft.Win32.RegistryValueKind Enumeration in the MSDN library.
Only the following data types are supported for list values: String and ExpandString.
You must specify this parameter when you configure a policy setting to set a registry value. You cannot specify this parameter with the Disable parameter.
The following values are permitted for this object type.
| Type: | RegistryValueKind |
| Accepted values: | Unknown, String, ExpandString, Binary, DWord, MultiString, QWord, None |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Value
Specifies the value data for the registry-based policy setting. You can specify a single value or an array of values. Use a comma-separated list to specify more than one value. Only the String and ExpandString data types are supported for an array of values.
At a minimum, you must specify this parameter together with the Type and Key parameters to configure a policy setting to set a registry value. You cannot specify this parameter with the Disable parameter.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ValueName
Specifies a value name or an array of value names for the registry-based policy setting. For instance, the registry key HKLM\Software\Policies\Microsoft\Windows NT\DNSClient can have a registry value with the following value name: UseDomainNameDevolution. Use a comma-separated list to specify more than one value name. Only the String and ExpandString data types are supported for an array of values.
You cannot specify this parameter with the ValuePrefix parameter.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ValuePrefix
Specifies a value name prefix for a registry-based policy setting for a list of registry values.
Configures a policy setting that creates the following registry values when Group Policy is applied on the client:
"HKLM\SOFTWARE\Policies\ExampleKey ExValue1" 100
"HKLM\SOFTWARE\Policies\ExampleKey ExValue2" 200
"HKLM\SOFTWARE\Policies\ExampleKey ExValue3" 300
Only the String and ExpandString data types are supported with the ValuePrefix parameter.
You cannot specify this parameter with the ValueName parameter or the Disable parameter.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
Microsoft.GroupPolicy.Gpo or Microsoft.GroupPolicy.PolicyRegistrySetting
You can pipe a GPO (in which to configure a registry-based policy setting), or a PolicyRegistrySetting object that represents a registry-based policy setting (to configure in a specified GPO) to this cmdlet. Collections that contain GPOs from different domains are not supported.
Outputs
Microsoft.GroupPolicy.Gpo
This cmdlet returns the GPO in which the registry-based policy setting has been configured.
Notes
The hive of the registry key that you specify, HKEY_LOCAL_MACHINE (HKLM) or HKEY_CURRENT_USER (HKCU), determines whether the registry-based policy setting is in Computer Configuration or User Configuration.
You can use the Domain parameter to explicitly specify the domain for this cmdlet.
If you do not explicitly specify the domain, the cmdlet uses a default domain. The default domain is the domain that is used to access network resources by the security context under which the current session is running. This domain is typically the domain of the user that is running the session. For instance, the domain of the user who started the session by opening Windows PowerShell from the Program Files menu, or the domain of a user that is specified in a runas command. However, computer startup and shutdown scripts run under the context of the LocalSystem account. The LocalSystem account is a built-in local account, and it accesses network resources under the context of the computer account. Therefore, when this cmdlet is run from a startup or shutdown script, the default domain is the domain to which the computer is joined.