PowerShell Adding and Modifying Registry Keys

Managing registry configurations in PowerShell is performed using core item cmdlets adapted for the Registry provider. You create new registry keys (containers) using New-Item, create new configuration values using New-ItemProperty, and update or overwrite existing values using Set-ItemProperty.

Creating Registry Keys with New-Item

A registry key functions as a container equivalent to a filesystem directory. The New-Item cmdlet creates new keys within any accessible hive (such as HKCU: or HKLM:).

New-Item -Path "HKCU:\Software\MyApp"

Hive: HKEY_CURRENT_USER\Software

Name                           Property
----                           --------
MyApp

where -Path the full registry path of the new key to create.

Creating Nested Keys

If parent keys in the path don't already exist, New-Item creates them automatically when -Force is used.

New-Item -Path "HKCU:\Software\MyApp\Settings" -Force

where -Force creates any missing intermediate keys in the path without prompting for confirmation (similar to mkdir -p), and avoids throwing an error if the target key already exists.

Checking Before Creating

Since New-Item throws an error if the key already exists, check first with Test-Path in scripts.

if (-not (Test-Path -Path "HKCU:\Software\MyApp")) {
    New-Item -Path "HKCU:\Software\MyApp"
}

Complete Key Creation Example

$newKey = New-Item -Path "HKCU:\Software\CorpApp\Settings" -Force

[PSCustomObject]@{
    KeyName   = $newKey.PSChildName
    FullPath  = $newKey.Name
    SubKeys   = $newKey.SubKeyCount
}

where:

• New-Item cmdlet used to create new container objects or files.
• -Path the hierarchical location of the registry key to create.
• -Force creates all intermediate parent keys in the hierarchy if they do not already exist, and avoids throwing an error if the target key already exists.
• $newKey.Name emits the fully qualified Windows registry hive and key path.

./create-registry-key.ps1

KeyName  FullPath                                        SubKeys
-------  --------                                        -------
Settings HKEY_CURRENT_USER\Software\CorpApp\Settings           0

Creating Registry Values with New-ItemProperty

A registry value is an individual data entry stored inside a registry key container. The New-ItemProperty cmdlet creates a new value entry, requiring a specified data type (-PropertyType) and initial payload (-Value).

New-ItemProperty -Path "HKCU:\Software\MyApp" -Name "ApiEndpoint" -Value "https://api.example.com" -PropertyType String

where:

• -Path is the registry key to add the value to (must already exist).
• -Name is the name of the new value.
• -Value is the data to store.
• -PropertyType is the registry data type: String, DWord, QWord, Binary, MultiString, or ExpandString.

ApiEndpoint  : https://api.example.com
PSPath       : Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\Software\MyApp
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\Software
PSChildName  : MyApp
PSDrive      : HKCU
PSProvider   : Microsoft.PowerShell.Core\Registry

Common Property Types

Complete Value Creation Example

New-ItemProperty -Path "HKCU:\Software\CorpApp\Settings" `
    -Name "LoggingLevel" `
    -PropertyType DWord `
    -Value 2 `
    -Force | Select-Object -Property PSPath, LoggingLevel

where:

• New-ItemProperty adds a new configuration value entry to an existing registry key.
• -Path is the target registry key container hosting the value.
• -Name is the label or identifier of the registry value.
• -PropertyType is the Windows registry storage type (e.g., DWord, String, Binary).
• -Value is the actual data payload to store in the property.
• -Force overwrites the value if an entry with the exact same name already exists.

./create-registry-property.ps1

PSPath                                                                          LoggingLevel
------                                                                          ------------
Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\Software\CorpApp\Settings            2

Modifying Existing Values with Set-ItemProperty

The Set-ItemProperty cmdlet modifies the data payload of an existing registry property. If the property does not exist at the target path, Set-ItemProperty creates it automatically, making it ideal for idempotent configuration scripts.

Set-ItemProperty -Path "HKCU:\Software\MyApp" -Name "ApiEndpoint" -Value "https://api-v2.example.com"

where:

• -Path is the registry key containing the value.
• -Name is the value name to update.
• -Value is the new data to assign.

Complete Modification Example

Set-ItemProperty -Path "HKCU:\Software\CorpApp\Settings" `
    -Name "LoggingLevel" `
    -Value 3

Get-ItemPropertyValue -Path "HKCU:\Software\CorpApp\Settings" -Name "LoggingLevel"

where:

• Set-ItemProperty updates the payload of an existing registry property or creates it if absent.
• -Path is the location of the target registry key.
• -Name is the name of the property to modify.
• -Value is the new data payload to assign.
• Get-ItemPropertyValue directly retrieves the raw value of a specified property without wrapping it in a custom object.

./set-registry-property.ps1

3

New-ItemProperty vs Set-ItemProperty

Practical Usage

Deploying an Application Configuration Key

A common deployment task is ensuring a registry key and its required settings exist, creating anything missing without erroring on re-runs.

$keyPath = "HKCU:\Software\MyApp"

if (-not (Test-Path -Path $keyPath)) {
    New-Item -Path $keyPath -Force | Out-Null
    Write-Output "Created key: $keyPath"
}

$settings = @{
    ApiEndpoint = "https://api.example.com"
    MaxRetries  = 3
    Debug       = 0
}

foreach ($name in $settings.Keys) {
    Set-ItemProperty -Path $keyPath -Name $name -Value $settings[$name]
}

Write-Output "Configuration applied."
Get-ItemProperty -Path $keyPath

where:

• $settings is a hashtable mapping value names to the desired data.
• Set-ItemProperty inside the loop creates each value if missing, or updates it if already present.

./deploy-app-config.ps1

Configuration applied.


ApiEndpoint  : https://api.example.com
Debug        : 0
MaxRetries   : 3
PSPath       : Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\Software\MyApp
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\Software
PSChildName  : MyApp
PSDrive      : HKCU
PSProvider   : Microsoft.PowerShell.Core\Registry

Enforcing Windows Legal Notice Banners

Administrators frequently configure mandatory security banners displayed to users prior to Windows interactive logon. These settings reside under the machine policy key in HKLM:.

$policyKey = "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System"

if (-not (Test-Path -Path $policyKey)) {
    New-Item -Path $policyKey -Force | Out-Null
}

$noticeTitle = "Authorized Access Only"
$noticeMessage = "Unauthorized access to this system is prohibited and monitored."

Set-ItemProperty -Path $policyKey -Name "legalnoticecaption" -Value $noticeTitle -Type String
Set-ItemProperty -Path $policyKey -Name "legalnoticetext" -Value $noticeMessage -Type String

Get-ItemProperty -Path $policyKey -Name "legalnoticecaption", "legalnoticetext" | 
    Select-Object -Property legalnoticecaption, legalnoticetext

where:

• Test-Path checks for the existence of the registry path prior to modification.
• -Type String explicitly ensures the property type is configured as a REG_SZ string entry within Set-ItemProperty.
• legalnoticecaption is the standard Windows registry value controlling the dialog box title of the logon warning.
• legalnoticetext is the standard Windows registry value controlling the body text of the logon warning banner.

./enforce-legal-notice.ps1

legalnoticecaption     legalnoticetext
------------------     ---------------
Authorized Access Only Unauthorized access to this system is prohibited and mo...