513 lines
16 KiB
Markdown
513 lines
16 KiB
Markdown
# about_Registry_Provider.help
|
|
|
|
|
|
|
|
ABOUT_REGISTRY_PROVIDER
|
|
|
|
|
|
Provider name
|
|
|
|
Registry
|
|
|
|
|
|
Drives
|
|
|
|
HKLM:, HKCU:
|
|
|
|
|
|
Capabilities
|
|
|
|
SHOULDPROCESS, USETRANSACTIONS
|
|
|
|
|
|
Short description
|
|
|
|
Provides access to the registry keys, entries, and values in PowerShell.
|
|
|
|
|
|
Detailed description
|
|
|
|
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 are not
|
|
components of that hierarchy. Instead, they are properties of each of the
|
|
keys.
|
|
|
|
The REGISTRY provider supports the following cmdlets, which are covered in
|
|
this article.
|
|
|
|
- Get-Location
|
|
- Set-Location
|
|
- Get-Item
|
|
- Get-ChildItem
|
|
- Invoke-Item
|
|
- Move-Item
|
|
- New-Item
|
|
- Remove-Item
|
|
- Get-ItemProperty
|
|
- Set-ItemProperty
|
|
- Remove-ItemProperty
|
|
- Clear-ItemProperty
|
|
- Get-Acl
|
|
- Set-Acl
|
|
|
|
|
|
Types exposed by this provider
|
|
|
|
Registry keys are represented as instances of the
|
|
Microsoft.Win32.RegistryKey class. Registry entries are represented as
|
|
instances of the PSCustomObject class.
|
|
|
|
|
|
Navigating the Registry drives
|
|
|
|
The REGISTRY provider exposes its data store as two default drives. The
|
|
registry location HKEY_LOCAL_MACHINE is mapped to the HKLM: drive and
|
|
HKEY_CURRENT_USER is mapped to the HKCU: drive. 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 now 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"
|
|
|
|
|
|
Displaying the contents of registry keys
|
|
|
|
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 are 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.
|
|
|
|
PS C:\ > 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 are not displayed. The Get-ChildItem cmdlet will
|
|
show you children items of the "Spooler" key, including each subkey's
|
|
properties. The parent keys properties are not shown when using
|
|
Get-ChildItem.
|
|
|
|
PS C:\> 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.
|
|
|
|
PS C:\> cd HKLM:\System\CurrentControlSet\Services\Spooler
|
|
PS 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.
|
|
|
|
-Get-Item -Get-ChildItem
|
|
|
|
|
|
Viewing registry key values
|
|
|
|
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.
|
|
|
|
PS C:\> 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
|
|
|
|
PS C:\> 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.
|
|
|
|
- Get-ItemProperty
|
|
- Get-ItemPropertyValue
|
|
|
|
|
|
Changing registry key values
|
|
|
|
The Set-ItemProperty cmdlet will set attributes for registry keys. 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.
|
|
|
|
PS C:\> Get-Service spooler | Select-Object Name, StartMode
|
|
|
|
Name StartType
|
|
---- ---------
|
|
spooler Automatic
|
|
|
|
PS C:\> $path = "HKLM:\SYSTEM\CurrentControlSet\Services\Spooler\"
|
|
PS C:\> Set-ItemProperty -Path $path -Name Start -Value 3
|
|
PS C:\> Get-Service spooler | Select-Object Name, StartMode
|
|
|
|
Name StartType
|
|
---- ---------
|
|
spooler Manual
|
|
|
|
PS C:\> 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.
|
|
|
|
- Set-Item
|
|
- Set-ItemProperty
|
|
|
|
|
|
Creating registry keys and values
|
|
|
|
The New-Item cmdlet will create registry keys with a name that you provide.
|
|
You can also use the mkdir function, which calls the New-Item cmdlet
|
|
internally.
|
|
|
|
PS HKLM:\SOFTWARE\> 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 -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.
|
|
|
|
|
|
Copying registry keys and values
|
|
|
|
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 does not 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.
|
|
|
|
- Copy-Item
|
|
- Copy-ItemProperty
|
|
|
|
|
|
Moving registry keys and values
|
|
|
|
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 does not 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 of the 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.
|
|
|
|
- Move-Item
|
|
- Move-ItemProperty
|
|
|
|
|
|
Renaming registry keys and values
|
|
|
|
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
|
|
|
|
|
|
Changing security descriptors
|
|
|
|
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.
|
|
|
|
- Get-Acl
|
|
- Set-Acl
|
|
|
|
|
|
Removing and clearing registry keys and values
|
|
|
|
You can remove contained items by using REMOVE-ITEM, but you will be
|
|
prompted to confirm the removal if the item contains anything else. The
|
|
following example attempts to delete a key "HKLM:\SOFTWARE\Contoso".
|
|
|
|
PS C:\> dir HKLM:\SOFTWARE\Contoso\
|
|
|
|
Hive: HKEY_LOCAL_MACHINE\SOFTWARE\Contoso
|
|
|
|
Name Property
|
|
---- --------
|
|
ChildKey
|
|
|
|
PS C:\> Remove-Item -Path HKLM:\SOFTWARE\Contoso
|
|
|
|
Confirm
|
|
The item at HKLM:\SOFTWARE\Contoso has children and the -Recurse
|
|
parameter was not 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.
|
|
|
|
PS HKLM:\SOFTWARE\> 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
|
|
|
|
PS HKLM:\SOFTWARE\> Clear-Item .\Contoso\
|
|
PS HKLM:\SOFTWARE\> Get-Item .\Contoso\
|
|
|
|
Hive: HKEY_LOCAL_MACHINE\SOFTWARE
|
|
|
|
Name Property
|
|
---- --------
|
|
Contoso
|
|
|
|
For more examples and cmdlet usage details see the following articles.
|
|
|
|
- Clear-Item
|
|
- Clear-ItemProperty
|
|
- Remove-Item
|
|
- Remove-ItemProperty
|
|
|
|
|
|
Dynamic parameters
|
|
|
|
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.
|
|
|
|
Type <Microsoft.Win32.RegistryValueKind>
|
|
|
|
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 is also
|
|
available on the Set-Item cmdlet in the registry drives, but it has no
|
|
effect.
|
|
|
|
Value Description
|
|
-------------- --------------------------------------------------------------
|
|
String Specifies a null-terminated string. Equivalent to REG_SZ.
|
|
ExpandString Specifies a null-terminated string that contains unexpanded
|
|
references to environment variables that are expanded when
|
|
the value is retrieved. Equivalent to REG_EXPAND_SZ.
|
|
Binary Specifies binary data in any form. Equivalent to REG_BINARY.
|
|
DWord Specifies a 32-bit binary number. Equivalent to REG_DWORD.
|
|
MultiString Specifies an array of null-terminated strings terminated by
|
|
two null characters. Equivalent to REG_MULTI_SZ.
|
|
QWord Specifies a 64-bit binary number. Equivalent to REG_QWORD.
|
|
Unknown Indicates an unsupported registry data type, such as
|
|
REG_RESOURCE_LIST.
|
|
|
|
Cmdlets supported
|
|
|
|
- Set-Item
|
|
- Set-ItemProperty
|
|
|
|
|
|
Using the pipeline
|
|
|
|
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.
|
|
|
|
|
|
Getting help
|
|
|
|
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:
|
|
|
|
|
|
See also
|
|
|
|
about_Providers
|