Set-RegistryKeyValue

Sets a value in a registry key.

Syntax

Set-RegistryKeyValue -Path <String> -Name <String> -String <String> [-Expand] [-Force] [-Quiet] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-RegistryKeyValue -Path <String> -Name <String> -Binary <Byte[]> [-Force] [-Quiet] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-RegistryKeyValue -Path <String> -Name <String> -DWord <Int32> [-Force] [-Quiet] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-RegistryKeyValue -Path <String> -Name <String> -UDWord <UInt32> [-Force] [-Quiet] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-RegistryKeyValue -Path <String> -Name <String> -QWord <Int64> [-Force] [-Quiet] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-RegistryKeyValue -Path <String> -Name <String> -UQWord <UInt64> [-Force] [-Quiet] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-RegistryKeyValue -Path <String> -Name <String> -Strings <String[]> [-Force] [-Quiet] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

The Set-RegistryKeyValue function sets the value of a registry key. If the key doesn't exist, it is created first. Uses PowerShell's New-ItemPropery to create the value if doesn't exist. Otherwise uses Set-ItemProperty to set the value.

DWord and QWord values are stored in the registry as unsigned integers. If you pass a negative integer for the DWord and QWord parameters, PowerShell will convert it to an unsigned integer before storing. You won't get the same negative number back.

To store integer values greater than [Int32]::MaxValue or [Int64]::MaxValue, use the UDWord and UQWord parameters, respectively, which are unsigned integers. These parameters were in Carbon 2.0.

In versions of Carbon before 2.0, you'll need to convert these large unsigned integers into signed integers. You can't do this with casting. Casting preservers the value, not the bits underneath. You need to re-interpret the bits. Here's some sample code:

# Carbon 1.0
$bytes = [BitConverter]::GetBytes( $unsignedInt )
$signedInt = [BitConverter]::ToInt32( $bytes, 0 )  # Or use `ToInt64` if you're working with 64-bit/QWord values
Set-RegistryKeyValue -Path $Path -Name 'MyUnsignedDWord' -DWord $signedInt

# Carbon 2.0
Set-RegistryKeyValue -Path $Path -Name 'MyUnsignedDWord' -UDWord $unsignedInt

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
Path String

The path to the registry key where the value should be set. Will be created if it doesn't exist.

true false
Name String

The name of the value being set.

true false
String String

The value's data. Creates a value for holding string data (i.e. REG_SZ). If $null, the value will be saved as an empty string.

true false
Expand SwitchParameter

The string should be expanded when retrieved. Creates a value for holding expanded string data (i.e. REG_EXPAND_SZ).

false false False
Binary Byte[]

The value's data. Creates a value for holding binary data (i.e. REG_BINARY).

true false
DWord Int32

The value's data. Creates a value for holding a 32-bit integer (i.e. REG_DWORD).

true false 0
UDWord UInt32

The value's data as an unsigned integer (i.e. UInt32). Creates a value for holding a 32-bit integer (i.e. REG_DWORD).

true false 0
QWord Int64

The value's data. Creates a value for holding a 64-bit integer (i.e. REG_QWORD).

true false 0
UQWord UInt64

The value's data as an unsigned long (i.e. UInt64). Creates a value for holding a 64-bit integer (i.e. REG_QWORD).

true false 0
Strings String[]

The value's data. Creates a value for holding an array of strings (i.e. REG_MULTI_SZ).

true false
Force SwitchParameter

Removes and re-creates the value. Useful for changing a value's type.

false false False
Quiet SwitchParameter

OBSOLETE. Will be removed in a future version of Carbon.

false false False
WhatIf SwitchParameter false false
Confirm SwitchParameter false false
CommonParameters This cmdlet supports common parameters. For more information type
Get-Help about_CommonParameters.

EXAMPLE 1

Set-RegistryKeyValue -Path 'hklm:\Software\Carbon\Test -Name Status -String foobar

Creates the Status string value under the hklm:\Software\Carbon\Test key and sets its value to foobar.

EXAMPLE 2

Set-RegistryKeyValue -Path 'hklm:\Software\Carbon\Test -Name ComputerName -String '%ComputerName%' -Expand

Creates an expandable string. When retrieving this value, environment variables will be expanded.

EXAMPLE 3

Set-RegistryKeyValue -Path 'hklm:\Software\Carbon\Test -Name Movies -String ('Signs','Star Wars','Raiders of the Lost Ark')

Sets a multi-string (i.e. array) value.

EXAMPLE 4

Set-RegistryKeyValue -Path hklm:\Software\Carbon\Test -Name 'SomeBytes' -Binary ([byte[]]@( 1, 2, 3, 4))

Sets a binary value (i.e. REG_BINARY).

EXAMPLE 5

Set-RegistryKeyValue -Path hklm:\Software\Carbon\Test -Name 'AnInt' -DWord 48043

Sets a binary value (i.e. REG_DWORD).

EXAMPLE 6

Set-RegistryKeyValue -Path hklm:\Software\Carbon\Test -Name 'AnInt64' -QWord 9223372036854775807

Sets a binary value (i.e. REG_QWORD).

EXAMPLE 7

Set-RegistryKeyValue -Path hklm:\Software\Carbon\Test -Name 'AnUnsignedInt' -UDWord [uint32]::MaxValue

Demonstrates how to set a registry value with an unsigned integer or an integer bigger than [int]::MaxValue.

The UDWord parameter was added in Carbon 2.0. In earlier versions of Carbon, you have to convert the unsigned int's bits to a signed integer:

$bytes = [BitConverter]::GetBytes( $unsignedInt )
$signedInt = [BitConverter]::ToInt32( $bytes, 0 )
Set-RegistryKeyValue -Path $Path -Name 'MyUnsignedDWord' -DWord $signedInt

EXAMPLE 8

Set-RegistryKeyValue -Path hklm:\Software\Carbon\Test -Name 'AnUnsignedInt64' -UQWord [uint64]::MaxValue

Demonstrates how to set a registry value with an unsigned 64-bit integer or a 64-bit integer bigger than [long]::MaxValue.

The `UQWord parameter was added in Carbon 2.0. In earlier versions of Carbon, you have to convert the unsigned int's bits to a signed integer:

$bytes = [BitConverter]::GetBytes( $unsignedInt )
$signedInt = [BitConverter]::ToInt64( $bytes, 0 )
Set-RegistryKeyValue -Path $Path -Name 'MyUnsignedDWord' -DWord $signedInt

EXAMPLE 9

Set-RegistryKeyValue -Path hklm:\Software\Carbon\Test -Name 'UsedToBeAStringNowShouldBeDWord' -DWord 1 -Force

Uses the Force parameter to delete the existing UsedToBeAStringNowShouldBeDWord before re-creating it. This flag is useful if you need to change the type of a registry value.