PowerShell Logo Small

Set-GPPrefRegistryValue



This is the built-in help made by Microsoft for the command 'Set-GPPrefRegistryValue', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Configures a Registry preference item under either Computer Configuration or User Configuration in a GPO.

SYNTAX


Set-GPPrefRegistryValue [-Disable] [-Domain <String>] [-Order <Int32>] [-Server <String>] [-Type <RegistryValueKind>] [-Value <PSObject>] [-ValueName <String>] -Action
<PreferenceAction> -Context <GpoConfiguration> -Guid <Guid> -Key <String> [-Confirm] [-WhatIf] [<CommonParameters>]
Set-GPPrefRegistryValue [-Name] <String> [-Disable] [-Domain <String>] [-Order <Int32>] [-Server <String>] [-Type <RegistryValueKind>] [-Value <PSObject>] [-ValueName
<String>] -Action <PreferenceAction> -Context <GpoConfiguration> -Key <String> [-Confirm] [-WhatIf] [<CommonParameters>]



Search powershellhelp.space

DESCRIPTION


Configures a Registry preference item under either Computer Configuration or User Configuration in a GPO.


You can configure the Registry preference item for either a registry key or a registry value:

-- For a registry key, specify the Key parameter, but do not specify the ValueName, Type, or Value parameters.

-- For a registry value, specify the Key parameter together with the ValueName, Type, and Value parameters. (All these parameters must be specified.)


You must specify the Context parameter (User or Computer) to indicate whether to configure the Registry preference item in Computer Configuration or User Configuration. You
must also specify the Action parameter to set the action that should be applied on the client. You can specify the GPO by its display name or its GUID. You can specify the
Disable parameter to create a Registry preference item that is disabled.


Note: This cmdlet configures new Registry preference items. It does not modify existing Registry preference items.


This cmdlet can take input from the pipeline:

--You can pipe GPO objects to this cmdlet to set a specified Registry preference item on one or more GPOs.

--You can pipe PreferenceRegistrySetting objects to this cmdlet to set one or more Registry preference items on a specified GPO.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/?linkid=287736
Get-GPPrefRegistryValue
Remove-GPPrefRegistryValue

REMARKS

<

Examples


-------------------------- EXAMPLE 1 --------------------------

C:\PS>Set-GPPrefRegistryValue -Name TestGPO -Context User -Key "HKCU\Software\Policies\Microsoft\Windows\Control Panel" -ValueName ScreenSaveIsSecure -Value "1" -Type String
-Action Update

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:16:28 PM
UserVersion : AD Version: 1, SysVol Version: 1
ComputerVersion : AD Version: 34, SysVol Version: 34
WmiFilter :



Description

-----------

This command configures a Registry preference item for the registry value "HKCU\Software\Policies\Microsoft\Windows\Control Panel\ ScreenSaveIsSecure" in User Configuration
for the "TestGPO" GPO. When the GPO is applied on a client, the registry value is updated with a data type of String (REG_SZ) and value data "1".




-------------------------- EXAMPLE 2 --------------------------

C:\PS>Set-GPPrefRegistryValue -Name TestGPO -Context User -Action Create -Key "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExampleKey" -ValueName ValueOne -Value NewData -Type
String



Description

-----------

This command configures a Registry preference item for the registry value "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExampleKey ValueOne" in User Configuration for the "TestGPO"
GPO. When the GPO is applied on a client, the registry value is created with a data type of String (REG_SZ) and value data "NewData".




-------------------------- EXAMPLE 3 --------------------------

C:\PS>Set-GPPrefRegistryValue -Guid 35c12ab3-956c-45d5-973b-46b17d225f47 -Context computer -Action Create -Key "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExampleKey\ExampleKey2"



Description

-----------

This command configures a Registry preference item for the registry key "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExampleKey\ExampleKey2" in Computer Configuration in the GPO
that has ID 35c12ab3-956c-45d5-973b-46b17d225f47. When the GPO is applied on a client, the registry key is created.




-------------------------- EXAMPLE 4 --------------------------

C:\PS>Remove-GPPrefRegistryValue -Name TestGPO -Context User -Key "HKLM\SOFTWARE\Microsoft\ExampleKey" -ValueName ValueOne | Set-GPPrefRegistryValue -Context User -Action
Create -Disable -Key "HKLM\SOFTWARE\Microsoft\ExampleKey" -ValueName ValueOne -Value SomeData -Type String



Description

-----------

This command creates a disabled Registry preference item for the registry value "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExampleKey ValueOne" in User Configuration in the
"TestGPO" GPO. First the Remove-GPPrefRegistryValue command removes any Registry preference items that configure the value from User Configuration. Then, the GPO ("TestGPO")
returned by the Remove-GPPrefRegistryValue is piped into Set-GPPrefRegistryValue to configure the disabled Registry preference item. After this command completes, the
disabled Registry preference item is the only Registry preference item associated with the registry value in User Configuration.

If the "TestGPO" GPO does not initially have a Registry preference item configured for the specified registry value, a non-terminating error occurs. You can suppress the
error message by supplying the ErrorAction parameter to Remove-GPPrefRegistryValue and setting its value to SilentlyContinue (-ErrorAction SilentlyContinue). For more
information about the ErrorAction parameter, see about_commonparameters.




-------------------------- EXAMPLE 5 --------------------------

C:\PS>Get-GPO -All | Remove-GPPrefRegistryValue -Context User -Key "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExampleKey" -ValueName ValueOne -ErrorAction SilentlyContinue |
Set-GPPrefRegistryValue -Context User -Action Update -Key "HKLM\SOFTWARE\Microsoft\ExampleKey" -ValueName ValueOne -Value SomeData -Type String



Description

-----------

This command configures a Registry preference item to update the registry value "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExampleKey ValueOne" for every GPO in the domain that
previously had a Registry preference item configured for that value in User Configuration.

First the Get-GPO cmdlet is invoked with the All parameter to get all the GPOs in the domain. These GPOs are piped into the Remove-GPPrefRegistryValue cmdlet. If the GPO
contains any Registry preference items configured for the specified key, they are removed. Remove-GPPrefRegistryValue only outputs a GPO to the pipeline if it removes a
Registry preference item from a GPO. Finally, these GPOs are piped to the Set-GPPrefRegistryValue to configure the Registry preference item to update the registry value.

If a GPO passed to Remove-GPPrefRegistryValue does not have a Registry preference item configured for the specified value, an non-terminating error occurs. The ErrorAction
parameter is set to SilentlyContinue (-ErrorAction SilentlyContinue) to suppress the error message. For more information about the ErrorAction parameter, see
about_commonparameters.




-------------------------- EXAMPLE 6 --------------------------

C:\PS>get-gpprefregistryvalue -name testgpo -context user -key hklm\software\microsoft\examplekey | set-gpprefregistryvalue -name testgpo-1 -context computer -order 1
-erroraction silentlycontinue

DisplayName : TestGPO-1
DomainName : contoso.com
Owner : CONTOSO\Domain Admins
Id : ef4d0f7e-1a1a-4fd1-b735-0bc6620e7f51
GpoStatus : AllSettingsEnabled
Description :
CreationTime : 3/1/2009 11:14:06 AM
ModificationTime : 3/1/2009 11:15:16 AM
UserVersion : AD Version: 0, SysVol Version: 0
ComputerVersion : AD Version: 1, SysVol Version: 1
WmiFilter :


DisplayName : TestGPO-1
DomainName : contoso.microsoft.com
Owner : CONTOSO\Domain Admins
Id : ef4d0f7e-1a1a-4fd1-b735-0bc6620e7f51
GpoStatus : AllSettingsEnabled
Description :
CreationTime : 3/1/2009 11:14:06 AM
ModificationTime : 3/1/2009 11:15:16 AM
UserVersion : AD Version: 0, SysVol Version: 0
ComputerVersion : AD Version: 2, SysVol Version: 2
WmiFilter :



Description

-----------

This command copies all Registry preference items that configure (first-level) values under the registry key "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ExampleKey" from User
Configuration in a source GPO (TestGPO) to Computer Configuration in destination GPO (TestGPO-1). A copy of the destination GPO (TestGPO-1) is returned for each Registration
preference item set (in this examlpe, 2).

The Get-GPPrefRegistryValue command gets all the Registry preference items that configure values under User Configuration in the source GPO. This command also returns all
first level subkeys that have values configured (though not the Registry preference items for the values themselves). These Registry preference items (and the subkeys) are
then piped into the Set-GPPrefRegistryValue command.

The Set-GPPrefRegistryValue command configures the Registry preference items for the registry values in the destination GPO.

-- The subkeys returned by Get-GPPrefRegistryValue do not have an Action property, and so a non-terminating error occurs for each subkey. The ErrorAction parameter is
specified (-ErrorAction SilentlyContinue) to suppress these error messages. For more information about the ErrorAction parameter, see about_commonparameters.

-- It is a good practice to specify an order of one (-Order 1) in Set-GPPrefRegistryValue when it accepts input from the pipeline. This is because Registry preference items
passed on the pipeline have an Order property. If the Order property of a Registry preference item passed on the pipeline is greater than the number of Registry preference
items currently configured in the destination GPO, an out of range error occurs and the Registry preference item is not configured in the destination GPO. By specifying the
order as one in the Set-GPPrefRegistryValue command, you override the Order property of the source Registry preference item, and prevent such errors from occurring.