about_Registry_Provider
Registry
HKLM:
, HKCU:
ShouldProcess, UseTransactions
Provides access to the registry keys, entries, and values in PowerShell.
The PowerShell Registry provider lets you get, add, change, clear, and delete registry keys, entries, and values in PowerShell.
The Registry drives are a hierarchical namespace containing the registry keys and subkeys on your computer. Registry entries and values aren't components of that hierarchy. Instead, they're properties of each of the keys.
The Registry provider supports the following cmdlets:
- Get-Location
- Set-Location
- Get-Item
- Get-ChildItem
- Invoke-Item
- Move-Item
- New-Item
- Remove-Item
- Clear-ItemProperty
- Get-ItemProperty
- New-ItemProperty
- Remove-ItemProperty
- Set-ItemProperty
- Get-Acl
- Set-Acl
The Registry provider returns registry data in one of two types:
- Microsoft.Win32.RegistryKey for registry keys
- PSCustomObject for registry values
The Registry provider exposes its data store as two default drives.
HKLM:
maps to theHKEY_LOCAL_MACHINE
registry hiveHKCU:
maps to theHKEY_CURRENT_USER
registry hive
To work with the registry, you can change your location to the HKLM:
drive
using the following command.
Set-Location HKLM:
To return to a file system drive, type the drive name. For example, type:
Set-Location C:
You can also work with the Registry provider from any other PowerShell
drive. To reference a registry key from another location, use the drive name
(HKLM:
, HKCU:
) in the path. Use a backslash (\
) or a forward slash (/
)
to indicate a level of the Registry drive.
PS C:\> cd HKLM:\Software
Note
PowerShell uses aliases to allow you a familiar way to work with provider
paths. Commands such as dir
and ls
are aliases for Get-ChildItem,
cd
is an alias for Set-Location, and pwd
is an alias for
Get-Location.
This last example shows another path syntax you can use to navigate the
Registry provider. This syntax uses the provider name, followed by two
colons ::
. This syntax allows you to use the full HIVE name, instead of the
mapped drive name HKLM
.
cd "Registry::HKEY_LOCAL_MACHINE\Software"
The registry is divided into keys, subkeys, and entries. For more information about registry structure, see Structure of the Registry.
In a Registry drive, each key is a container. A key can contain any number
of keys. A registry key that has a parent key is called a subkey. You can
use Get-ChildItem
to view registry keys and Set-Location
to navigate to
a key path.
Registry values are attributes of a registry key. In the Registry drive, they're called Item Properties. A registry key can have both children keys and item properties.
In this example, the difference between Get-Item
and Get-ChildItem
is
shown. When you use Get-Item
on the "Spooler" registry key, you can view its
properties.
Get-Item -Path HKLM:\SYSTEM\CurrentControlSet\Services\Spooler
Hive: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services
Name Property
---- --------
Spooler DependOnService : {RPCSS, http}
Description : @%systemroot%\system32\spoolsv.exe,-2
DisplayName : @%systemroot%\system32\spoolsv.exe,-1
ErrorControl : 1
FailureActions : {16, 14, 0, 0...}
Group : SpoolerGroup
ImagePath : C:\WINDOWS\System32\spoolsv.exe
ObjectName : LocalSystem
RequiredPrivileges : {SeTcbPrivilege, SeImpersonatePrivilege, ...
ServiceSidType : 1
Start : 2
Type : 27
Each registry key can also have subkeys. When you use Get-Item
on a registry
key, the subkeys aren't displayed. The Get-ChildItem
cmdlet shows you subkeys
of the "Spooler" key, including each subkey's properties. The parent keys
properties aren't shown when using Get-ChildItem
.
Get-ChildItem -Path HKLM:\SYSTEM\CurrentControlSet\Services\Spooler
Hive: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Spooler
Name Property
---- --------
Performance Close : PerfClose
Collect : PerfCollect
Collect Timeout : 2000
Library : C:\Windows\System32\winspool.drv
Object List : 1450
Open : PerfOpen
Open Timeout : 4000
Security Security : {1, 0, 20, 128...}
The Get-Item
cmdlet can also be used on the current location. The following
example navigates to the "Spooler" registry key and gets the item properties.
The dot .
is used to indicate the current location.
cd HKLM:\System\CurrentControlSet\Services\Spooler
Get-Item .
Hive: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services
Name Property
---- --------
Spooler DependOnService : {RPCSS, http}
Description : @%systemroot%\system32\spoolsv.exe,-2
...
For more information on the cmdlets covered in this section, see the following articles.
Registry key values are stored as properties of each registry key. The
Get-ItemProperty
cmdlet views registry key properties using the name you
specify. The result is a PSCustomObject containing the properties you
specify.
The Following example uses the Get-ItemProperty
cmdlet to view all
properties. Storing the resulting object in a variable allows you to access
the desired property value.
$p = Get-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\Spooler
$p.DependOnService
RPCSS
http
Specifying a value for the -Name
parameter selects the properties you
specify and returns the PSCustomObject. The following example shows
the difference in output when you use the -Name
parameter.
Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Wbem
BUILD : 17134.1
Installation Directory : C:\WINDOWS\system32\WBEM
MOF Self-Install Directory : C:\WINDOWS\system32\WBEM\MOF
PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Wbem
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft
PSChildName : Wbem
PSDrive : HKLM
PSProvider : Microsoft.PowerShell.Core\Registry
Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Wbem -Name BUILD
BUILD : 17134.1
PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Wbem
PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft
PSChildName : Wbem
PSDrive : HKLM
PSProvider : Microsoft.PowerShell.Core\Registry
Beginning in PowerShell 5.0, the Get-ItemPropertyValue
cmdlet returns
only the value of the property you specify.
Get-ItemPropertyValue -Path HKLM:\SOFTWARE\Microsoft\Wbem -Name BUILD
17134.1
For more information on the cmdlets used in this section, see the following articles.
The Set-ItemProperty
cmdlet sets registry values associated with a registry
key. The following example uses Set-ItemProperty
to change the spooler
service start type to manual. The example changes the StartType back to
Automatic
using the Set-Service
cmdlet.
Get-Service spooler | Select-Object Name, StartMode
Name StartType
---- ---------
spooler Automatic
$path = "HKLM:\SYSTEM\CurrentControlSet\Services\Spooler\"
Set-ItemProperty -Path $path -Name Start -Value 3
Get-Service spooler | Select-Object Name, StartMode
Name StartType
---- ---------
spooler Manual
Set-Service -Name Spooler -StartupType Automatic
Each registry key has a default value. You can change the default
value
for a registry key with either Set-Item
or Set-ItemProperty
.
Set-ItemProperty -Path HKLM:\SOFTWARE\Contoso -Name "(default)" -Value "one"
Set-Item -Path HKLM:\SOFTWARE\Contoso -Value "two"
For more information on the cmdlets used in this section, see the following articles.
The New-Item
cmdlet creates new registry keys with a name that you provide.
You can also use the mkdir
function, which calls the New-Item
cmdlet
internally.
mkdir ContosoCompany
Hive: HKEY_LOCAL_MACHINE\SOFTWARE
Name Property
---- --------
ContosoCompany
You can use the New-ItemProperty
cmdlet to create values in a registry key
that you specify. The following example creates a new DWORD value on the
ContosoCompany registry key.
$path = "HKLM:\SOFTWARE\ContosoCompany"
New-ItemProperty -Path $path -Name Test -Type DWORD -Value 1
Note
Review the dynamic parameters section in this article for other allowed type values.
For detailed cmdlet usage, see New-ItemProperty.
In the Registry provider, use the Copy-Item
cmdlet copies registry keys
and values. Use the Copy-ItemProperty
cmdlet to copy registry values only.
The following command copies the "Contoso" registry key, and its properties to
the specified location HKLM:\Software\Fabrikam
.
Copy-Item
creates the destination key if it doesn't exist. If the destination
key exists, Copy-Item
creates a duplicate of the source key as a child item
(subkey) of the destination key.
Copy-Item -Path HKLM:\Software\Contoso -Destination HKLM:\Software\Fabrikam
The following command uses the Copy-ItemProperty
cmdlet to copy the "Server"
value from the "Contoso" key to the "Fabrikam" key.
$source = "HKLM:\SOFTWARE\Contoso"
$dest = "HKLM:\SOFTWARE\Fabrikam"
Copy-ItemProperty -Path $source -Destination $dest -Name Server
For more information on the cmdlets used in this section, see the following articles.
The Move-Item
and Move-ItemProperty
cmdlets behave like their "Copy"
counterparts. If the destination exists, Move-Item
moves the source key
underneath the destination key. If the destination key doesn't exist, the
source key is moved to the destination path.
The following command moves the "Contoso" key to the path
HKLM:\SOFTWARE\Fabrikam
.
Move-Item -Path HKLM:\SOFTWARE\Contoso -Destination HKLM:\SOFTWARE\Fabrikam
This command moves all properties from HKLM:\SOFTWARE\ContosoCompany
to
HKLM:\SOFTWARE\Fabrikam
.
$source = "HKLM:\SOFTWARE\Contoso"
$dest = "HKLM:\SOFTWARE\Fabrikam"
Move-ItemProperty -Path $source -Destination $dest -Name *
For more information on the cmdlets used in this section, see the following articles.
You can rename registry keys and values just like you would files and folders.
Rename-Item
renames registry keys, while Rename-ItemProperty
renames
registry values.
$path = "HKLM:\SOFTWARE\Contoso"
Rename-ItemProperty -Path $path -Name ContosoTest -NewName FabrikamTest
Rename-Item -Path $path -NewName Fabrikam
You can restrict access to registry keys using the Get-Acl
and Set-Acl
cmdlets. The following example adds a new user with full control to the
HKLM:\SOFTWARE\Contoso
registry key.
$acl = Get-Acl -Path HKLM:\SOFTWARE\Contoso
$rule = New-Object System.Security.AccessControl.RegistryAccessRule `
("CONTOSO\jsmith", "FullControl", "Allow")
$acl.SetAccessRule($rule)
$acl | Set-Acl -Path HKLM:\SOFTWARE\Contoso
For more examples and cmdlet usage details see the following articles.
You can remove contained items using Remove-Item
. You are prompted to confirm
the removal if the item contains anything else. The following example attempts
to delete a key HKLM:\SOFTWARE\Contoso
.
dir HKLM:\SOFTWARE\Contoso\
Hive: HKEY_LOCAL_MACHINE\SOFTWARE\Contoso
Name Property
---- --------
ChildKey
Remove-Item -Path HKLM:\SOFTWARE\Contoso
Confirm
The item at HKLM:\SOFTWARE\Contoso has children and the -Recurse
parameter wasn't specified. If you continue, all children will be removed
with the item. Are you sure you want to continue?
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help
(default is "Y"):
To delete contained items without prompting, specify the -Recurse
parameter.
Remove-Item -Path HKLM:\SOFTWARE\Contoso -Recurse
If you wanted to remove all items within HKLM:\SOFTWARE\Contoso
but not
HKLM:\SOFTWARE\Contoso
itself, use a trailing backslash \
followed by a
wildcard.
Remove-Item -Path HKLM:\SOFTWARE\Contoso\* -Recurse
This command deletes the "ContosoTest" registry value from the
HKLM:\SOFTWARE\Contoso
registry key.
Remove-ItemProperty -Path HKLM:\SOFTWARE\Contoso -Name ContosoTest
Clear-Item
clears all registry values for a key. The following example
clears all values from the HKLM:\SOFTWARE\Contoso
registry key. To clear
only a specific property, use Clear-ItemProperty
.
Get-Item .\Contoso\
Hive: HKEY_LOCAL_MACHINE\SOFTWARE
Name Property
---- --------
Contoso Server : {a, b, c}
HereString : {This is text which contains
newlines. It also contains "quoted" strings}
(default) : 1
Clear-Item .\Contoso\
Get-Item .\Contoso\
Hive: HKEY_LOCAL_MACHINE\SOFTWARE
Name Property
---- --------
Contoso
For more examples and cmdlet usage details see the following articles.
Dynamic parameters are cmdlet parameters that are added by a PowerShell provider and are available only when the cmdlet is being used in the provider-enabled drive.
Establishes or changes the data type of a registry value. The default is
String
(REG_SZ).
This parameter works as designed on the Set-ItemProperty cmdlet. It's also available on the Set-Item cmdlet in the registry drives, but it has no effect.
String
- Used for REG_SZ values. Pass a[System.String]
object to the Value parameter.ExpandString
- Used for REG_EXPAND_SZ values. Pass a[System.String]
object to the Value parameter. The string should contain unexpanded references to environment variables that are expanded when the value is retrieved.Binary
- Used for REG_BINARY values. Pass a[System.Byte[]]
object to the Value parameter.DWord
- Used for REG_DWORD values. Pass a[System.Int32]
object to the Value parameter.MultiString
- Used for REG_MULTI_SZ values. Pass a[System.String[]]
object to the Value parameter.QWord
- Used for REG_QWORD values. Pass a[System.Int64]
object to the Value parameter.Unknown
- Indicates an unsupported registry data type, such as REG_RESOURCE_LIST values.
Provider cmdlets accept pipeline input. You can use the pipeline to simplify task by sending provider data from one cmdlet to another provider cmdlet. To read more about how to use the pipeline with provider cmdlets, see the cmdlet references provided throughout this article.
Beginning in Windows PowerShell 3.0, you can get customized help topics for provider cmdlets that explain how those cmdlets behave in a file system drive.
To get the help topics that are customized for the file system drive, run a
Get-Help
command in a file system drive or use the Path parameter to
specify a file system drive.
Get-Help Get-ChildItem
Get-Help Get-ChildItem -Path HKLM:
PowerShell feedback
PowerShell is an open source project. Select a link to provide feedback: