How To Edit The Windows Registry In PowerShell

This article explains how to edit the Windows registry in PowerShell.

Question

How can I access the Windows Registry in PowerShell so I can create, update and delete keys and values?

Short Answer

Use the Get-ItemProperty and Set-ItemProperty Cmdlets:

# get the data from a specific registry key value
Get-ItemProperty "HKLM:SOFTWAREMyRegistryKey" |
    % { $_.MyKeyValue };

# set the data for a specific registry key value
Set-ItemProperty "HKLM:SOFTWAREMyRegistryKey" -Name "MyKeyValue" -Value "Some Data";

Long Answer

When playing with the Windows Registry, the common *-Item Cmdlets are our friends:

As are the common *-ItemProperty Cmdlets:

We can also make use of this helper:

Test-Path

Registry Key Path

We need to keep in mind the path format of a registry key. Best to tuck it into a variable to avoid retyping it all the time:

$NewRegKey = "HKLM:SOFTWAREMyNewKey";

Check If Key Exists

To check whether a given key already exists we can use Test-Path, which will return True or False depending on it:

Test-Path $NewRegKey;

Create New Key

To create a new registry key we can use New-Item:

New-Item $NewRegKey;

Set Default Key Data

To change the (default) key data, which every key starts with, we can use Set-Item:

Set-Item $NewRegKey -Value "Some Default Data";

Create New Key Property

To create a new key property we have two basic ways to go about it. We can specify the property type or we can let it be inferred from the data being passed.

To create a new key property while inferring the data type, we can use either New-ItemProperty or Set-ItemProperty. Both accomplish the same:

New-ItemProperty $NewRegKey -Name "MyKeyProperty" -Value "MyKeyData"
Set-ItemProperty $NewRegKey -Name "MyKeyProperty" -Value "MyKeyData"

To create a new key property while specifying the data type, we have to use New-ItemProperty, while passing a type defined in the Microsoft.Win32.RegistryValueKind enumeration. We must therefore use one of:

String
ExpandString
Binary
DWord
MultiString
QWord
Unknown (which defaults to String)

For example, this creates a new integer property on the registry key:

New-ItemProperty $NewRegKey -Name "MyKeyProperty" -Value "12345" -PropertyType "DWord"

Update Key Property

To update this property we can now use Set-ItemProperty:

Set-ItemProperty $NewRegKey -Name "MyKeyProperty" -Value "54321"

We have to be careful with Set-ItemProperty though, as it will override the existing data type in order to fit in incompatible data. For example, running this on our current integer property will turn it into a string property without warning:

Set-ItemProperty $NewRegKey -Name "MyKeyProperty" -Value "Some String Data"

Remove Key Property

Removing a key property is as easy as calling Remove-ItemProperty:

Remove-ItemProperty $NewRegKey -Name "MyKeyProperty"

Remove Registry Key

Removing a key is also easy. We only need to call Remove-Item:

Remove-Item $NewRegKey

Renaming

To rename a registry key or a key property we can make use of Rename-Item and Rename-ItemProperty respectively:

Rename-Item $NewRegKey -NewName "OtherRegKey"
Rename-ItemProperty $NewRegKey -Name "MyKeyProperty" -NewName "MyRenamedKeyProperty"

Scripting

Now that we have a grasp of the tools we can use to access the registry, we start putting them to use in a non-destructive registry update script, the kind of which we would use in an installation or configuration process:

# the key
$RegKey = "HKLM:SOFTWAREMyNewKey";

# create the key if it is not there yet
if (-not (Test-Path $RegKey))
{
    New-Item $RegKey
}

# remove an old key property
$PropertyToBeRemoved = "MyPropertyToBeRemoved";
if (Get-ItemProperty $RegKey -Name $PropertyToBeRemoved -ErrorAction SilentlyContinue)
{
    Remove-ItemProperty $RegKey -Name $PropertyToBeRemoved
}

# add a new property if it does not exist yet
$PropertyNameToBeAdded = "MyPropertyToBeAdded";
$PropertyDataToBeAdded = "12345";
$PropertyTypeToBeAdded = "DWord";
if (-not (Get-ItemProperty $RegKey -Name $PropertyNameToBeAdded -ErrorAction SilentlyContinue))
{
    New-ItemProperty $RegKey -Name $PropertyNameToBeAdded -Value $PropertyDataToBeAdded -PropertyType $PropertyTypeToBeAdded
}

As we can see, this simple script incrementally updates the registry in a non-destructive manner. This pattern allows upgrade installations to add new configurations while retaining existing ones.

We can simplify this pattern further to ease administration a bit:

# the key name
$RegKey = "HKLM:SOFTWAREMyNewKey";

# the items to create and their default values
$RegItems =
    ( "Property1", "String", "Some String Data" ),
    ( "Property2", "DWord", 12345 ),
    ( "Property3", "QWord", 1234567890 );

# create the key if needed
if (-not (Test-Path $RegKey))
{
    New-Item $RegKey;
}

# create each key property if needed
$RegItems | % {
    If (-not (Get-ItemProperty $RegKey -Name $_[0] -ErrorAction SilentlyContinue))
    {
        New-ItemProperty $RegKey -Name $_[0] -PropertyType $_[1] -Value $_[2];
    }
};

With further tweaking, this script could grab its registry values from a dedicated configuration file or some other easy to edit metadata file. I’ll leave that up to you.

On Distributed Computing