diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index bd9a4497e575..3119e60b4c50 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -374,6 +374,136 @@ "redirect_url": "/powershell/scripting/powershell-scripting", "redirect_document_id": "False" }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Add-Content-for-FileSystem.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Clear-Content-for-FileSystem.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-ChildItem-for-FileSystem.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-Content-for-FileSystem.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-Item-for-FileSystem.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Remove-Item-for-FileSystem.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Set-Content-for-FileSystem.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Test-Path-for-FileSystem.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Security/Providers/get-childitem-for-certificate.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Security/Providers/move-item-for-certificate.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Security/Providers/new-item-for-certificate.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Security/Providers/remove-item-for-certificate.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-ClientCertificate.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-InitializationParameters.md", + "redirect_url": "/powershell/module/Microsoft.WSMan.Management/Providers/about_WSMan_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Listener.md", + "redirect_url": "/powershell/module/Microsoft.WSMan.Management/Providers/about_WSMan_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Plugin.md", + "redirect_url": "/powershell/module/Microsoft.WSMan.Management/Providers/about_WSMan_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Resources.md", + "redirect_url": "/powershell/module/Microsoft.WSMan.Management/Providers/about_WSMan_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Security.md", + "redirect_url": "/powershell/module/Microsoft.WSMan.Management/Providers/about_WSMan_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/Alias-Provider.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_Alias_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/Environment-Provider.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_Environment_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/Function-Provider.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_Function_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/Registry-Provider.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_Registry_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Core/Providers/Variable-Provider.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Core/Providers/about_Variable_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.PowerShell.Security/Providers/Certificate-Provider.md", + "redirect_url": "/powershell/module/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider?view=powershell-6", + "redirect_document_id": false + }, + { + "source_path": "reference/6/Microsoft.WSMan.Management/Providers/WSMan-Provider.md", + "redirect_url": "/powershell/module/Microsoft.WSMan.Management/Providers/about_WSMan_Provider?view=powershell-6", + "redirect_document_id": false + }, { "source_path": "reference/virtual-directory/core-powershell/ise/using-the-windows-powershell-ise.md", "redirect_url": "/powershell/scripting/core-powershell/ise/introducing-the-windows-powershell-ise", diff --git a/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md index 0f246eb788b2..c78000cd0425 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md @@ -1,4 +1,3 @@ - --- ms.date: 06/09/2017 schema: 2.0.0 @@ -119,7 +118,7 @@ $Hash ```output Name Value ---- ----- -Copyright © Microsoft Corporation. All rights reserved. +Copyright © Microsoft Corporation. All rights reserved. ModuleToProcess Microsoft.PowerShell.ScheduledJob.dll FormatsToProcess PSScheduledJob.Format.ps1xml PowerShellVersion 3.0 diff --git a/reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md index d03519b35c24..894c7ce84894 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md @@ -33,8 +33,7 @@ However, because temporary drives are known only to PowerShell, you cannot acces The following features are added to `New-PSDrive` in Windows PowerShell 3.0: -* **Mapped network drives** - +- Mapped network drives. You can use the **Persist** parameter of `New-PSDrive` to create Windows mapped network drives. Unlike temporary PowerShell drives, Windows mapped network drives are not session-specific. They are saved in Windows and they can be managed by using standard Windows tools, such as File Explorer and Net Use. @@ -42,17 +41,14 @@ The following features are added to `New-PSDrive` in Windows PowerShell 3.0: When your command is scoped locally (no dot-sourcing), the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which the command is running. If you are running `New-PSDrive` inside a script, and you want the drive to persist indefinitely, you must dot-source the script. For best results, to force a new drive to persist indefinitely, add the **Scope** parameter to your command, and set its value to Global. - -* **External drives** - +- External drives. When an external drive is connected to the computer, PowerShell automatically adds a **PSDrive** to the file system that represents the new drive. You do not have to restart PowerShell. Similarly, when an external drive is disconnected from the computer, PowerShell automatically deletes the **PSDrive** that represents the removed drive. +- Credentials for UNC Paths. -* **Credentials for UNC Paths** - - When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. - Otherwise, **Credential** is not effective when you are creating new file system drives. +When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. +Otherwise, **Credential** is not effective when you are creating new file system drives. ## EXAMPLES @@ -70,7 +66,7 @@ P FileSystem \\Server01\Public This command creates a temporary PowerShell drive named P: that is mapped to the \\\\Server01\Public network share. -It uses the *Name* parameter to specify a name for the drive, the *PSProvider* parameter to specify the PowerShell FileSystem provider, and the *Root* parameter to specify the network share. +It uses the **Name** parameter to specify a name for the drive, the **PSProvider** parameter to specify the PowerShell FileSystem provider, and the **Root** parameter to specify the network share. When the command finishes, the contents of the \\\\Server01\Public share appear in the P: drive. To see them, type: `dir P:`. @@ -90,9 +86,9 @@ MyDocs FileSystem C:\Documents and Settings\User01\My Documents This command creates a temporary PowerShell drive that provides quick access to a local directory. It creates a drive named MyDocs: that is mapped to the "C:\Documents and Settings\User01\My Documents" directory on the local computer. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell FileSystem provider, *Root* to specify the path of the My Documents folder, and the *Description* parameter to create a description of the drive. +It uses **Name** to specify a name for the drive, **PSProvider** to specify the PowerShell FileSystem provider, **Root** to specify the path of the My Documents folder, and the **Description** parameter to create a description of the drive. -When the command finishes, the contents of the My Documents folder appear in the MyDocs: drive. +When the command finishes, the contents of the My Documents folder appear in the `MyDocs:` drive. To see them, type: `dir MyDocs:`. ### Example 3: Create a drive for a registry key @@ -110,9 +106,9 @@ MyCompany Registry HKEY_LOCAL_MACHINE\Software\MyCo... This command creates a temporary PowerShell drive that provides quick access to a frequently checked registry key. It creates a drive named MyCompany that is mapped to the `HKLM\Software\MyCompany` registry key. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell Registry provider, and *Root* to specify the registry key. +It uses **Name** to specify a name for the drive, **PSProvider** to specify the PowerShell Registry provider, and **Root** to specify the registry key. -When the command finishes, the contents of the MyCompany key appear in the MyCompany: drive. +When the command finishes, the contents of the MyCompany key appear in the `MyCompany:` drive. To see them, type: `dir MyCompany:`. ### Example 4: Create a persisted mapped network drive @@ -128,14 +124,14 @@ Status Local Remote Network OK S: \\Server01\Scripts Microsoft Windows Network ``` -This command creates the S mapped network drive on the local computer. +This command creates the 'S' mapped network drive on the local computer. The 'S' drive is mapped to the \\\\Server01\Scripts network share. The command uses `New-PSDrive` to create the mapped network drive. It uses *Persist* to create a Windows mapped network drive that is saved on the local computer. -The command uses *Name* to specify a letter name that Windows accepts and *Root* to specify a location on a remote computer. -It uses *PSProvider* to specify the FileSystem provider. +The command uses **Name** to specify a letter name that Windows accepts and **Root** to specify a location on a remote computer. +It uses **PSProvider** to specify the FileSystem provider. The resulting drive can be viewed in other PowerShell sessions on the local computer, in Windows Explorer, and in other tools, such as Net Use. @@ -200,7 +196,7 @@ X: \\products\public Disconnected This example shows the difference between a persistent mapped network drive and a temporary PowerShell drive that is mapped to the same network share. -If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the X: drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. +If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the `X:` drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. ## PARAMETERS @@ -209,10 +205,10 @@ If you close the PowerShell session and then open a new one, the PSDrive: drive Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, this cmdlet prompts you for a password. -Starting in Windows PowerShell 3.0, when the value of the *Root* parameter is a UNC path, you can use credentials to create file system drives. +Starting in Windows PowerShell 3.0, when the value of the **Root** parameter is a UNC path, you can use credentials to create file system drives. This parameter is not supported by all PowerShell providers. ```yaml @@ -271,13 +267,13 @@ Indicates that this cmdlet creates a Windows mapped network drive. Mapped network drives are saved in Windows on the local computer. They are persistent, not session-specific, and can be viewed and managed in File Explorer and other tools. -When you scope the command locally, that is, without dot-sourcing, the *Persist* parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. +When you scope the command locally, that is, without dot-sourcing, the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. If you run `New-PSDrive` inside a script, and you want the new drive to persist indefinitely, you must dot-source the script. -For best results, to force a new drive to persist, specify Global as the value of the *Scope* parameterin addition to adding *Persist* to your command. +For best results, to force a new drive to persist, specify Global as the value of the **Scope** parameter in addition to adding **Persist** to your command. -The name of the drive must be a letter, such as D or E. -The value of *Root* parameter must be a UNC path of a different computer. -The value of the *PSProvider* parameter must be FileSystem. +The name of the drive must be a letter, such as 'D' or 'E'. +The value of **Root** parameter must be a UNC path of a different computer. +The value of the **PSProvider** parameter must be FileSystem. To disconnect a Windows mapped network drive, use the `Remove-PSDrive` cmdlet. When you disconnect a Windows mapped network drive, the mapping is permanently deleted from the computer, not just deleted from the current session. @@ -397,7 +393,7 @@ Accept wildcard characters: False Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. -For more information, see about_Transactions. +For more information, see [about_Transactions](../Microsoft.PowerShell.Core/About/about_Transactions.md). ```yaml Type: SwitchParameter @@ -436,4 +432,4 @@ You cannot pipe input to this cmdlet. [Remove-PSDrive](Remove-PSDrive.md) -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) diff --git a/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md index 330bd754880f..b121d6c48e4b 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md @@ -118,7 +118,7 @@ $Hash ```output Name Value ---- ----- -Copyright © Microsoft Corporation. All rights reserved. +Copyright © Microsoft Corporation. All rights reserved. ModuleToProcess Microsoft.PowerShell.ScheduledJob.dll FormatsToProcess PSScheduledJob.Format.ps1xml PowerShellVersion 3.0 diff --git a/reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md index 0ea13e507c62..18900db64f63 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md @@ -33,8 +33,7 @@ However, because temporary drives are known only to PowerShell, you cannot acces The following features are added to `New-PSDrive` in Windows PowerShell 3.0: -* **Mapped network drives** - +- Mapped network drives. You can use the **Persist** parameter of `New-PSDrive` to create Windows mapped network drives. Unlike temporary PowerShell drives, Windows mapped network drives are not session-specific. They are saved in Windows and they can be managed by using standard Windows tools, such as File Explorer and Net Use. @@ -42,17 +41,14 @@ The following features are added to `New-PSDrive` in Windows PowerShell 3.0: When your command is scoped locally (no dot-sourcing), the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which the command is running. If you are running `New-PSDrive` inside a script, and you want the drive to persist indefinitely, you must dot-source the script. For best results, to force a new drive to persist indefinitely, add the **Scope** parameter to your command, and set its value to Global. - -* **External drives** - +- External drives. When an external drive is connected to the computer, PowerShell automatically adds a **PSDrive** to the file system that represents the new drive. You do not have to restart PowerShell. Similarly, when an external drive is disconnected from the computer, PowerShell automatically deletes the **PSDrive** that represents the removed drive. +- Credentials for UNC Paths. -* **Credentials for UNC Paths** - - When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. - Otherwise, **Credential** is not effective when you are creating new file system drives. +When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. +Otherwise, **Credential** is not effective when you are creating new file system drives. ## EXAMPLES @@ -70,7 +66,7 @@ P FileSystem \\Server01\Public This command creates a temporary PowerShell drive named P: that is mapped to the \\\\Server01\Public network share. -It uses the *Name* parameter to specify a name for the drive, the *PSProvider* parameter to specify the PowerShell FileSystem provider, and the *Root* parameter to specify the network share. +It uses the **Name** parameter to specify a name for the drive, the **PSProvider** parameter to specify the PowerShell FileSystem provider, and the **Root** parameter to specify the network share. When the command finishes, the contents of the \\\\Server01\Public share appear in the P: drive. To see them, type: `dir P:`. @@ -90,9 +86,9 @@ MyDocs FileSystem C:\Documents and Settings\User01\My Documents This command creates a temporary PowerShell drive that provides quick access to a local directory. It creates a drive named MyDocs: that is mapped to the "C:\Documents and Settings\User01\My Documents" directory on the local computer. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell FileSystem provider, *Root* to specify the path of the My Documents folder, and the *Description* parameter to create a description of the drive. +It uses **Name** to specify a name for the drive, **PSProvider** to specify the PowerShell FileSystem provider, **Root** to specify the path of the My Documents folder, and the **Description** parameter to create a description of the drive. -When the command finishes, the contents of the My Documents folder appear in the MyDocs: drive. +When the command finishes, the contents of the My Documents folder appear in the `MyDocs:` drive. To see them, type: `dir MyDocs:`. ### Example 3: Create a drive for a registry key @@ -110,9 +106,9 @@ MyCompany Registry HKEY_LOCAL_MACHINE\Software\MyCo... This command creates a temporary PowerShell drive that provides quick access to a frequently checked registry key. It creates a drive named MyCompany that is mapped to the `HKLM\Software\MyCompany` registry key. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell Registry provider, and *Root* to specify the registry key. +It uses **Name** to specify a name for the drive, **PSProvider** to specify the PowerShell Registry provider, and **Root** to specify the registry key. -When the command finishes, the contents of the MyCompany key appear in the MyCompany: drive. +When the command finishes, the contents of the MyCompany key appear in the `MyCompany:` drive. To see them, type: `dir MyCompany:`. ### Example 4: Create a persisted mapped network drive @@ -128,14 +124,14 @@ Status Local Remote Network OK S: \\Server01\Scripts Microsoft Windows Network ``` -This command creates the S mapped network drive on the local computer. +This command creates the 'S' mapped network drive on the local computer. The 'S' drive is mapped to the \\\\Server01\Scripts network share. The command uses `New-PSDrive` to create the mapped network drive. It uses *Persist* to create a Windows mapped network drive that is saved on the local computer. -The command uses *Name* to specify a letter name that Windows accepts and *Root* to specify a location on a remote computer. -It uses *PSProvider* to specify the FileSystem provider. +The command uses **Name** to specify a letter name that Windows accepts and **Root** to specify a location on a remote computer. +It uses **PSProvider** to specify the FileSystem provider. The resulting drive can be viewed in other PowerShell sessions on the local computer, in Windows Explorer, and in other tools, such as Net Use. @@ -200,7 +196,7 @@ X: \\products\public Disconnected This example shows the difference between a persistent mapped network drive and a temporary PowerShell drive that is mapped to the same network share. -If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the X: drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. +If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the `X:` drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. ## PARAMETERS @@ -209,10 +205,10 @@ If you close the PowerShell session and then open a new one, the PSDrive: drive Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, this cmdlet prompts you for a password. -Starting in Windows PowerShell 3.0, when the value of the *Root* parameter is a UNC path, you can use credentials to create file system drives. +Starting in Windows PowerShell 3.0, when the value of the **Root** parameter is a UNC path, you can use credentials to create file system drives. This parameter is not supported by all PowerShell providers. ```yaml @@ -271,13 +267,13 @@ Indicates that this cmdlet creates a Windows mapped network drive. Mapped network drives are saved in Windows on the local computer. They are persistent, not session-specific, and can be viewed and managed in File Explorer and other tools. -When you scope the command locally, that is, without dot-sourcing, the *Persist* parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. +When you scope the command locally, that is, without dot-sourcing, the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. If you run `New-PSDrive` inside a script, and you want the new drive to persist indefinitely, you must dot-source the script. -For best results, to force a new drive to persist, specify Global as the value of the *Scope* parameterin addition to adding *Persist* to your command. +For best results, to force a new drive to persist, specify Global as the value of the **Scope** parameter in addition to adding **Persist** to your command. -The name of the drive must be a letter, such as D or E. -The value of *Root* parameter must be a UNC path of a different computer. -The value of the *PSProvider* parameter must be FileSystem. +The name of the drive must be a letter, such as 'D' or 'E'. +The value of **Root** parameter must be a UNC path of a different computer. +The value of the **PSProvider** parameter must be FileSystem. To disconnect a Windows mapped network drive, use the `Remove-PSDrive` cmdlet. When you disconnect a Windows mapped network drive, the mapping is permanently deleted from the computer, not just deleted from the current session. @@ -397,7 +393,7 @@ Accept wildcard characters: False Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. -For more information, see about_Transactions. +For more information, see [about_Transactions](../Microsoft.PowerShell.Core/About/about_Transactions.md). ```yaml Type: SwitchParameter @@ -436,4 +432,4 @@ You cannot pipe input to this cmdlet. [Remove-PSDrive](Remove-PSDrive.md) -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) diff --git a/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md index 1dac5777115b..2987b1ba08fb 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md @@ -118,7 +118,7 @@ $Hash ```output Name Value ---- ----- -Copyright © Microsoft Corporation. All rights reserved. +Copyright © Microsoft Corporation. All rights reserved. ModuleToProcess Microsoft.PowerShell.ScheduledJob.dll FormatsToProcess PSScheduledJob.Format.ps1xml PowerShellVersion 3.0 diff --git a/reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md index 26ca7f7d7d69..390558a98de8 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md @@ -33,8 +33,7 @@ However, because temporary drives are known only to PowerShell, you cannot acces The following features are added to `New-PSDrive` in Windows PowerShell 3.0: -* **Mapped network drives** - +- Mapped network drives. You can use the **Persist** parameter of `New-PSDrive` to create Windows mapped network drives. Unlike temporary PowerShell drives, Windows mapped network drives are not session-specific. They are saved in Windows and they can be managed by using standard Windows tools, such as File Explorer and Net Use. @@ -42,17 +41,14 @@ The following features are added to `New-PSDrive` in Windows PowerShell 3.0: When your command is scoped locally (no dot-sourcing), the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which the command is running. If you are running `New-PSDrive` inside a script, and you want the drive to persist indefinitely, you must dot-source the script. For best results, to force a new drive to persist indefinitely, add the **Scope** parameter to your command, and set its value to Global. - -* **External drives** - +- External drives. When an external drive is connected to the computer, PowerShell automatically adds a **PSDrive** to the file system that represents the new drive. You do not have to restart PowerShell. Similarly, when an external drive is disconnected from the computer, PowerShell automatically deletes the **PSDrive** that represents the removed drive. +- Credentials for UNC Paths. -* **Credentials for UNC Paths** - - When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. - Otherwise, **Credential** is not effective when you are creating new file system drives. +When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. +Otherwise, **Credential** is not effective when you are creating new file system drives. ## EXAMPLES @@ -70,7 +66,7 @@ P FileSystem \\Server01\Public This command creates a temporary PowerShell drive named P: that is mapped to the \\\\Server01\Public network share. -It uses the *Name* parameter to specify a name for the drive, the *PSProvider* parameter to specify the PowerShell FileSystem provider, and the *Root* parameter to specify the network share. +It uses the **Name** parameter to specify a name for the drive, the **PSProvider** parameter to specify the PowerShell FileSystem provider, and the **Root** parameter to specify the network share. When the command finishes, the contents of the \\\\Server01\Public share appear in the P: drive. To see them, type: `dir P:`. @@ -90,9 +86,9 @@ MyDocs FileSystem C:\Documents and Settings\User01\My Documents This command creates a temporary PowerShell drive that provides quick access to a local directory. It creates a drive named MyDocs: that is mapped to the "C:\Documents and Settings\User01\My Documents" directory on the local computer. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell FileSystem provider, *Root* to specify the path of the My Documents folder, and the *Description* parameter to create a description of the drive. +It uses **Name** to specify a name for the drive, **PSProvider** to specify the PowerShell FileSystem provider, **Root** to specify the path of the My Documents folder, and the **Description** parameter to create a description of the drive. -When the command finishes, the contents of the My Documents folder appear in the MyDocs: drive. +When the command finishes, the contents of the My Documents folder appear in the `MyDocs:` drive. To see them, type: `dir MyDocs:`. ### Example 3: Create a drive for a registry key @@ -110,9 +106,9 @@ MyCompany Registry HKEY_LOCAL_MACHINE\Software\MyCo... This command creates a temporary PowerShell drive that provides quick access to a frequently checked registry key. It creates a drive named MyCompany that is mapped to the `HKLM\Software\MyCompany` registry key. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell Registry provider, and *Root* to specify the registry key. +It uses **Name** to specify a name for the drive, **PSProvider** to specify the PowerShell Registry provider, and **Root** to specify the registry key. -When the command finishes, the contents of the MyCompany key appear in the MyCompany: drive. +When the command finishes, the contents of the MyCompany key appear in the `MyCompany:` drive. To see them, type: `dir MyCompany:`. ### Example 4: Create a persisted mapped network drive @@ -128,14 +124,14 @@ Status Local Remote Network OK S: \\Server01\Scripts Microsoft Windows Network ``` -This command creates the S mapped network drive on the local computer. +This command creates the 'S' mapped network drive on the local computer. The 'S' drive is mapped to the \\\\Server01\Scripts network share. The command uses `New-PSDrive` to create the mapped network drive. It uses *Persist* to create a Windows mapped network drive that is saved on the local computer. -The command uses *Name* to specify a letter name that Windows accepts and *Root* to specify a location on a remote computer. -It uses *PSProvider* to specify the FileSystem provider. +The command uses **Name** to specify a letter name that Windows accepts and **Root** to specify a location on a remote computer. +It uses **PSProvider** to specify the FileSystem provider. The resulting drive can be viewed in other PowerShell sessions on the local computer, in Windows Explorer, and in other tools, such as Net Use. @@ -200,7 +196,7 @@ X: \\products\public Disconnected This example shows the difference between a persistent mapped network drive and a temporary PowerShell drive that is mapped to the same network share. -If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the X: drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. +If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the `X:` drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. ## PARAMETERS @@ -225,10 +221,10 @@ Accept wildcard characters: False Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, this cmdlet prompts you for a password. -Starting in Windows PowerShell 3.0, when the value of the *Root* parameter is a UNC path, you can use credentials to create file system drives. +Starting in Windows PowerShell 3.0, when the value of the **Root** parameter is a UNC path, you can use credentials to create file system drives. This parameter is not supported by all PowerShell providers. ```yaml @@ -311,13 +307,13 @@ Indicates that this cmdlet creates a Windows mapped network drive. Mapped network drives are saved in Windows on the local computer. They are persistent, not session-specific, and can be viewed and managed in File Explorer and other tools. -When you scope the command locally, that is, without dot-sourcing, the *Persist* parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. +When you scope the command locally, that is, without dot-sourcing, the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. If you run `New-PSDrive` inside a script, and you want the new drive to persist indefinitely, you must dot-source the script. -For best results, to force a new drive to persist, specify Global as the value of the *Scope* parameterin addition to adding *Persist* to your command. +For best results, to force a new drive to persist, specify Global as the value of the **Scope** parameter in addition to adding **Persist** to your command. -The name of the drive must be a letter, such as D or E. -The value of *Root* parameter must be a UNC path of a different computer. -The value of the *PSProvider* parameter must be FileSystem. +The name of the drive must be a letter, such as 'D' or 'E'. +The value of **Root** parameter must be a UNC path of a different computer. +The value of the **PSProvider** parameter must be FileSystem. To disconnect a Windows mapped network drive, use the `Remove-PSDrive` cmdlet. When you disconnect a Windows mapped network drive, the mapping is permanently deleted from the computer, not just deleted from the current session. @@ -380,7 +376,7 @@ Accept wildcard characters: False Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. -For more information, see about_Transactions. +For more information, see [about_Transactions](../Microsoft.PowerShell.Core/About/about_Transactions.md). ```yaml Type: SwitchParameter @@ -413,7 +409,7 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -436,4 +432,4 @@ You cannot pipe input to this cmdlet. [Remove-PSDrive](Remove-PSDrive.md) -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) diff --git a/reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md index 26ca7f7d7d69..390558a98de8 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md @@ -33,8 +33,7 @@ However, because temporary drives are known only to PowerShell, you cannot acces The following features are added to `New-PSDrive` in Windows PowerShell 3.0: -* **Mapped network drives** - +- Mapped network drives. You can use the **Persist** parameter of `New-PSDrive` to create Windows mapped network drives. Unlike temporary PowerShell drives, Windows mapped network drives are not session-specific. They are saved in Windows and they can be managed by using standard Windows tools, such as File Explorer and Net Use. @@ -42,17 +41,14 @@ The following features are added to `New-PSDrive` in Windows PowerShell 3.0: When your command is scoped locally (no dot-sourcing), the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which the command is running. If you are running `New-PSDrive` inside a script, and you want the drive to persist indefinitely, you must dot-source the script. For best results, to force a new drive to persist indefinitely, add the **Scope** parameter to your command, and set its value to Global. - -* **External drives** - +- External drives. When an external drive is connected to the computer, PowerShell automatically adds a **PSDrive** to the file system that represents the new drive. You do not have to restart PowerShell. Similarly, when an external drive is disconnected from the computer, PowerShell automatically deletes the **PSDrive** that represents the removed drive. +- Credentials for UNC Paths. -* **Credentials for UNC Paths** - - When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. - Otherwise, **Credential** is not effective when you are creating new file system drives. +When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. +Otherwise, **Credential** is not effective when you are creating new file system drives. ## EXAMPLES @@ -70,7 +66,7 @@ P FileSystem \\Server01\Public This command creates a temporary PowerShell drive named P: that is mapped to the \\\\Server01\Public network share. -It uses the *Name* parameter to specify a name for the drive, the *PSProvider* parameter to specify the PowerShell FileSystem provider, and the *Root* parameter to specify the network share. +It uses the **Name** parameter to specify a name for the drive, the **PSProvider** parameter to specify the PowerShell FileSystem provider, and the **Root** parameter to specify the network share. When the command finishes, the contents of the \\\\Server01\Public share appear in the P: drive. To see them, type: `dir P:`. @@ -90,9 +86,9 @@ MyDocs FileSystem C:\Documents and Settings\User01\My Documents This command creates a temporary PowerShell drive that provides quick access to a local directory. It creates a drive named MyDocs: that is mapped to the "C:\Documents and Settings\User01\My Documents" directory on the local computer. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell FileSystem provider, *Root* to specify the path of the My Documents folder, and the *Description* parameter to create a description of the drive. +It uses **Name** to specify a name for the drive, **PSProvider** to specify the PowerShell FileSystem provider, **Root** to specify the path of the My Documents folder, and the **Description** parameter to create a description of the drive. -When the command finishes, the contents of the My Documents folder appear in the MyDocs: drive. +When the command finishes, the contents of the My Documents folder appear in the `MyDocs:` drive. To see them, type: `dir MyDocs:`. ### Example 3: Create a drive for a registry key @@ -110,9 +106,9 @@ MyCompany Registry HKEY_LOCAL_MACHINE\Software\MyCo... This command creates a temporary PowerShell drive that provides quick access to a frequently checked registry key. It creates a drive named MyCompany that is mapped to the `HKLM\Software\MyCompany` registry key. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell Registry provider, and *Root* to specify the registry key. +It uses **Name** to specify a name for the drive, **PSProvider** to specify the PowerShell Registry provider, and **Root** to specify the registry key. -When the command finishes, the contents of the MyCompany key appear in the MyCompany: drive. +When the command finishes, the contents of the MyCompany key appear in the `MyCompany:` drive. To see them, type: `dir MyCompany:`. ### Example 4: Create a persisted mapped network drive @@ -128,14 +124,14 @@ Status Local Remote Network OK S: \\Server01\Scripts Microsoft Windows Network ``` -This command creates the S mapped network drive on the local computer. +This command creates the 'S' mapped network drive on the local computer. The 'S' drive is mapped to the \\\\Server01\Scripts network share. The command uses `New-PSDrive` to create the mapped network drive. It uses *Persist* to create a Windows mapped network drive that is saved on the local computer. -The command uses *Name* to specify a letter name that Windows accepts and *Root* to specify a location on a remote computer. -It uses *PSProvider* to specify the FileSystem provider. +The command uses **Name** to specify a letter name that Windows accepts and **Root** to specify a location on a remote computer. +It uses **PSProvider** to specify the FileSystem provider. The resulting drive can be viewed in other PowerShell sessions on the local computer, in Windows Explorer, and in other tools, such as Net Use. @@ -200,7 +196,7 @@ X: \\products\public Disconnected This example shows the difference between a persistent mapped network drive and a temporary PowerShell drive that is mapped to the same network share. -If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the X: drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. +If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the `X:` drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. ## PARAMETERS @@ -225,10 +221,10 @@ Accept wildcard characters: False Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, this cmdlet prompts you for a password. -Starting in Windows PowerShell 3.0, when the value of the *Root* parameter is a UNC path, you can use credentials to create file system drives. +Starting in Windows PowerShell 3.0, when the value of the **Root** parameter is a UNC path, you can use credentials to create file system drives. This parameter is not supported by all PowerShell providers. ```yaml @@ -311,13 +307,13 @@ Indicates that this cmdlet creates a Windows mapped network drive. Mapped network drives are saved in Windows on the local computer. They are persistent, not session-specific, and can be viewed and managed in File Explorer and other tools. -When you scope the command locally, that is, without dot-sourcing, the *Persist* parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. +When you scope the command locally, that is, without dot-sourcing, the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. If you run `New-PSDrive` inside a script, and you want the new drive to persist indefinitely, you must dot-source the script. -For best results, to force a new drive to persist, specify Global as the value of the *Scope* parameterin addition to adding *Persist* to your command. +For best results, to force a new drive to persist, specify Global as the value of the **Scope** parameter in addition to adding **Persist** to your command. -The name of the drive must be a letter, such as D or E. -The value of *Root* parameter must be a UNC path of a different computer. -The value of the *PSProvider* parameter must be FileSystem. +The name of the drive must be a letter, such as 'D' or 'E'. +The value of **Root** parameter must be a UNC path of a different computer. +The value of the **PSProvider** parameter must be FileSystem. To disconnect a Windows mapped network drive, use the `Remove-PSDrive` cmdlet. When you disconnect a Windows mapped network drive, the mapping is permanently deleted from the computer, not just deleted from the current session. @@ -380,7 +376,7 @@ Accept wildcard characters: False Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. -For more information, see about_Transactions. +For more information, see [about_Transactions](../Microsoft.PowerShell.Core/About/about_Transactions.md). ```yaml Type: SwitchParameter @@ -413,7 +409,7 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -436,4 +432,4 @@ You cannot pipe input to this cmdlet. [Remove-PSDrive](Remove-PSDrive.md) -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) diff --git a/reference/6/CimCmdlets/New-CimSession.md b/reference/6/CimCmdlets/New-CimSession.md index 00465f7b48b3..41d912a25fe2 100644 --- a/reference/6/CimCmdlets/New-CimSession.md +++ b/reference/6/CimCmdlets/New-CimSession.md @@ -5,7 +5,6 @@ locale: en-us keywords: powershell,cmdlet external help file: Microsoft.Management.Infrastructure.CimCmdlets.dll-Help.xml --- - # New-CimSession ## SYNOPSIS @@ -16,7 +15,7 @@ Creates a CIM session. ### CredentialParameterSet (Default) -```powershell +``` New-CimSession [-Authentication ] [[-Credential] ] [[-ComputerName] ] [-Name ] [-OperationTimeoutSec ] [-SkipTestConnection] [-Port ] [-SessionOption ] [] @@ -24,7 +23,7 @@ New-CimSession [-Authentication ] [[-Credential ### CertificatePrameterSet -```powershell +``` New-CimSession [-CertificateThumbprint ] [[-ComputerName] ] [-Name ] [-OperationTimeoutSec ] [-SkipTestConnection] [-Port ] [-SessionOption ] [] @@ -148,8 +147,8 @@ Enter the certificate thumbprint of the certificate. Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts. -To get a certificate thumbprint, use the [`Get-Item`](../Microsoft.Powershell.Management/Get-Item.md) or [`Get-ChildItem`](../Microsoft.Powershell.Management/Get-ChildItem.md) cmdlets in the PowerShell [Certificate Provider](../Microsoft.PowerShell.Security/Providers/Certificate-Provider.md). -For more information about using the PowerShell Certificate provider, type `Get-Help Certificate`, or see [Certificate Provider](../Microsoft.PowerShell.Security/Providers/Certificate-Provider.md) on docs.microsoft.com. +To get a certificate thumbprint, use the [`Get-Item`](../Microsoft.Powershell.Management/Get-Item.md) or [`Get-ChildItem`](../Microsoft.Powershell.Management/Get-ChildItem.md) cmdlets in the PowerShell Certificate Provider. +For more information about using the PowerShell Certificate provider, type `Get-Help Certificate`, or see [Certificate Provider](../Microsoft.PowerShell.Security/Providers/about_Certificate_Provider.md). ```yaml Type: String @@ -266,9 +265,9 @@ The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port fo Before using an alternate port, you must configure the WinRM listener on the remote computer to listen at that port. Use the following commands to configure the listener: - winrm delete winrm/config/listener?Address=*+Transport=HTTP +`winrm delete winrm/config/listener?Address=*+Transport=HTTP` - winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\"} +`winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\"}` Do not use the **Port** parameter unless you must. The port setting in the command applies to all computers or sessions on which the command runs. @@ -322,8 +321,9 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. -For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/6/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index da8d7c45b0a0..ac2fcf7f48d1 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -27,47 +27,46 @@ following rules. - If you specify the path to a command, PowerShell runs the command at the location specified by the path. - For example, the following command runs the FindDocs.ps1 script in the - "C:\\TechDocs" directory: +For example, the following command runs the "FindDocs.ps1" script in the +"C:\\TechDocs" directory: - ``` - C:\TechDocs\FindDocs.ps1 - ``` +``` +C:\TechDocs\FindDocs.ps1 +``` - As a security feature, PowerShell does not run executable (native) commands, - including PowerShell scripts, unless the command is located in a path that is - listed in the Path environment variable `$env:path` or unless you specify the - path to the script file. +As a security feature, PowerShell does not run executable (native) commands, +including PowerShell scripts, unless the command is located in a path that is +listed in the Path environment variable `$env:path` or unless you specify the +path to the script file. - To run a script that is in the current directory, specify the full path, or - type a dot `.` to represent the current directory. +To run a script that is in the current directory, specify the full path, or +type a dot `.` to represent the current directory. - For example, to run the FindDocs.ps1 file in the current directory, type: +For example, to run the FindDocs.ps1 file in the current directory, type: - ``` - .\FindDocs.ps1 - ``` +``` +.\FindDocs.ps1 +``` - If you do not specify a path, PowerShell uses the following precedence order when it runs commands: - 1. Alias 2. Function 3. Cmdlet 4. Native Windows commands - Therefore, if you type "help", PowerShell first looks for an alias named - `help`, then a function named `Help`, and finally a cmdlet named `Help`. It - runs the first `help` item that it finds. +Therefore, if you type "help", PowerShell first looks for an alias named +`help`, then a function named `Help`, and finally a cmdlet named `Help`. It +runs the first `help` item that it finds. - For example, if your session contains a cmdlet and a function, both named - `Get-Map`, when you type `Get-Map`, PowerShell runs the function. +For example, if your session contains a cmdlet and a function, both named +`Get-Map`, when you type `Get-Map`, PowerShell runs the function. - When the session contains items of the same type that have the same name, - PowerShell runs the newer item. +When the session contains items of the same type that have the same name, +PowerShell runs the newer item. - For example, if you import another `Get-Date` cmdlet from a module, when you - type `Get-Date`, PowerShell runs the imported version over the native one. +For example, if you import another `Get-Date` cmdlet from a module, when you +type `Get-Date`, PowerShell runs the imported version over the native one. ## Hidden and replaced items @@ -115,7 +114,7 @@ CommandType Name ModuleName Function Get-Date ``` -The following command uses the **All** parameter to get all "Get-Date" +The following command uses the **All** parameter to get all "`Get-Date`" commands. ```powershell @@ -140,7 +139,7 @@ commands. Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet -by qualifying it with its module name `Microsoft.PowerShell.Utility`. +by qualifying it with its module name **Microsoft.PowerShell.Utility**. Use this preferred method when writing scripts that you intend to distribute. You cannot predict which commands might be present in @@ -236,6 +235,7 @@ name acronym to the nouns in your commands. Also, when you import commands into your session from a PowerShell module or from another session, use the `Prefix` parameter of the [Import-Module](../../Microsoft.PowerShell.Core/Import-Module.md) or + [Import-PSSession](../../Microsoft.PowerShell.Utility/Import-PSSession.md) cmdlet to add a prefix to the nouns in the names of commands. @@ -251,11 +251,18 @@ For more information, see `Import-Module` and `Import-PSSession` below. ## See also -- [about_Path_Syntax](about_Path_Syntax.md) -- [about_Aliases](about_Aliases.md) -- [about_Functions](about_Functions.md) -- [Alias-Provider](../../Microsoft.PowerShell.Core/Providers/Alias-Provider.md) -- [Function-Provider](../../Microsoft.PowerShell.Core/Providers/Function-Provider.md) -- [Get-Command](../../Microsoft.PowerShell.Core/Get-Command.md) -- [Import-Module](../../Microsoft.PowerShell.Core/Import-Module.md) -- [Import-PSSession](../../Microsoft.PowerShell.Utility/Import-PSSession.md) \ No newline at end of file +[about_Path_Syntax](about_Path_Syntax.md) + +[about_Aliases](about_Aliases.md) + +[about_Functions](about_Functions.md) + +[Alias-Provider](../Providers/about_Alias_Provider.md) + +[Function-Provider](../Providers/about_Function_Provider.md) + +[Get-Command](../../Microsoft.PowerShell.Core/Get-Command.md) + +[Import-Module](../../Microsoft.PowerShell.Core/Import-Module.md) + +[Import-PSSession](../../Microsoft.PowerShell.Utility/Import-PSSession.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index a31f279bec16..f747e4b0610c 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -294,7 +294,7 @@ $path = [System.Environment]::GetEnvironmentVariable("PSModulePath", ``` For more information about the methods of the System.Environment class, see -[Environment Methods](https://go.microsoft.com/fwlink/?LinkId=242783) in +[Environment Methods](/dotnet/api/system.environment) in MSDN. You can add also add a command that changes the value to your profile or use @@ -305,5 +305,6 @@ For more information, see [about_Modules](about_Modules.md). ## SEE ALSO -- [Environment (provider)](../Providers/Environment-Provider.md) -- [about_Modules](about_Modules.md) \ No newline at end of file +[Environment (provider)](../Providers/about_Environment_Provider.md) + +[about_Modules](about_Modules.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Providers.md b/reference/6/Microsoft.PowerShell.Core/About/about_Providers.md index b5a4aca6980f..54043622094a 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Providers.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Providers.md @@ -229,7 +229,15 @@ type a Set-Location command, such as: Set-Location HKLM:\SOFTWARE\ ``` -You can also use relative references to locations. A dot (.) represents the +If any element in the fully qualified name includes spaces, you must enclose +the name in quotation marks `" "`. The following example shows a fully +qualified path that includes spaces. + +``` +"C:\Program Files\Internet Explorer\iexplore.exe" +``` + +You can also use relative references to locations. A dot (`.`) represents the current location. For example, if you are in the HKLM:\Software\Microsoft registry key, and you want to list the registry subkeys in the HKLM:\Software\Microsoft\PowerShell key, type the following command: @@ -238,6 +246,15 @@ HKLM:\Software\Microsoft\PowerShell key, type the following command: Get-ChildItem .\PowerShell ``` +In addition, two dots (`..`) refers to the directory or container directly +above your current location. You can combine dots (`.`) and double dots (`..`) +along with your paths to work through a provider hierarchy. + +``` +PS C:\Windows\System32> cd "..\..\Program Files" +PS C:\Program Files> +``` + ## Provider Home Providers also have a **Home** location. This location is shared by all diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/Alias-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/Alias-Provider.md deleted file mode 100644 index 3dacb701d447..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/Alias-Provider.md +++ /dev/null @@ -1,312 +0,0 @@ ---- -ms.date: 11/15/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Alias Provider -online version: http://go.microsoft.com/fwlink/?LinkId=834943 ---- - -# *Alias* provider - -## Provider name - -Alias - -## Drives - -`Alias:` - -## Short description - -Provides access to the PowerShell aliases and the values that they represent. - -## Detailed description - -The PowerShell **Alias** provider lets you get, add, change, clear, and delete aliases in PowerShell. - -An alias is an alternate name for a cmdlet, function, executable file, including scripts. -PowerShell includes a set of built-in aliases. -You can add your own aliases to the current session and to your PowerShell profile. - -The **Alias** provider is a flat namespace that contains only the alias objects. -The aliases have no child items. - -Each alias is an instance of the [System.Management.Automation.AliasInfo](https://msdn.microsoft.com/library/system.management.automation.aliasinfo) class. - -The **Alias** provider exposes its data store in the `Alias:` drive. -To work with aliases, you can change your location to the `Alias:` drive by using the following command: - -```powershell -Set-Location Alias: -``` - -Or, you can work from any other PowerShell drive. -To reference an alias from another location, use the `Alias:` drive name in the path. - -PowerShell includes a set of cmdlets that are designed to view and to change aliases: - -- [Export-Alias](../../Microsoft.PowerShell.Utility/Export-Alias.md) -- [Get-Alias](../../Microsoft.PowerShell.Utility/Get-Alias.md) -- [Import-Alias](../../Microsoft.PowerShell.Utility/Import-Alias.md) -- [New-Alias](../../Microsoft.PowerShell.Utility/New-Alias.md) -- [Set-Alias](../../Microsoft.PowerShell.Utility/Set-Alias.md) - -When you use these cmdlets, you do not need to specify the `Alias:` drive in the name. - -The **Alias** provider supports all the cmdlets that have the *Item* noun except for the [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) cmdlet. -It also supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. -The **Alias** provider does not support the cmdlets that have the *ItemProperty* noun and does not support the `-Filter` parameter in any cmdlet. - -All changes to the aliases affect the current session only. -To save the changes, add the changes to the PowerShell profile. -Or, use the [Export-Alias](../../Microsoft.PowerShell.Utility/Export-Alias.md) and [Import-Alias](../../Microsoft.PowerShell.Utility/Import-Alias.md) cmdlets. - -## Capabilities - -ShouldProcess - -## Examples - -### Getting to the `Alias:` drive - -#### Example 1 - -This command changes the current location to the `Alias:` drive. -You can use this command from any drive in PowerShell. -To return to a file system drive, type the drive name. -For example, type `set-location c:`. - -```powershell -Set-Location Alias: -``` - -### Getting aliases - -#### Example 1 - -This command gets a list of all the aliases in the current session. -You can use this command in any PowerShell drive. - -```powershell -Get-Item -Path Alias: -``` - -#### Example 2 - -This command gets the `ls` alias. -Because it includes the path, you can use it in any PowerShell drive. - -```powershell -Get-Item -Path Alias:ls -``` - -If you are in the `Alias:` drive, you can omit the drive name from the path. - -#### Example 3 - -This command gets a list of the aliases that are associated with the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet. -It uses the `Definition` property, which stores the cmdlet name. - -```powershell -Get-Item -Path Alias:* | Where-Object {$_.Definition -eq "Get-ChildItem"} -``` - -#### Example 4 - -This command gets the list of all the aliases when the current location is the `Alias:` drive. -It uses a wildcard character `*` to indicate all the contents of the current location. - -```powershell -Get-Item -Path * -``` - -In the `Alias:` drive, a dot `.`, which represents the current location, and a wildcard character `*`, which represents all items in the current location, have the same effect. -For example, `Get-Item -Path .` or `Get-Item \*` produce the same result. - -### Creating a new alias - -#### Example 1 - -This command creates the `serv` alias for the [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) cmdlet. -Because the current location is in the `Alias:` drive, the value of the `-Path` parameter is a dot `.`. -The dot represents the current location. - -This command also uses the `-Options` dynamic parameter to set the **AllScope** and **Constant** options on the alias. -The `-Options` parameter is available in the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet only when you are in the `Alias:` drive. - -```powershell -New-Item -Path . -Name serv -Value Get-Service -Options "AllScope,Constant" -``` - -If you are in the `Alias:` drive, you can omit the drive name from the path. - -#### Example 2 - -You can create an alias for any item that invokes a command. -This command creates the `np` alias for `Notepad.exe`. - -```powershell -New-Item -Path Alias:np -Value c:\windows\notepad.exe -``` - -#### Example 3 - -You can create an alias for any function. -You can use this feature to create an alias that includes both a cmdlet and its parameters. - -The first command creates the `CD32` function, which changes the current directory to the `System32` directory. -The second command creates the `go` alias for the `CD32` function. -The semi-colon `;` is the command separator. - -When the command is complete, you can use either `CD32` or `go` to invoke the function. - -```powershell -function CD32 {Set-Location -Path c:\windows\system32}; Set-Item -Path Alias:go -Value CD32 -``` - -### Displaying the properties and methods of aliases - -#### Example 1 - -This command uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get all aliases. -The pipeline operator `|` sends the results to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet, which displays the methods and properties of the object. - -```powershell -Get-Item -Path Alias:* | Get-Member -``` - -When you pipe a collection of objects to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), such as the collection of aliases in the `Alias:` drive, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately. -Then, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) returns information about each object type that it finds. -If all the objects are of the same type, it returns information about the single object type. -In this case, all the aliases are [AliasInfo](https://msdn.microsoft.com/library/system.management.automation.aliasinfo) objects. -To get information about the collection of [AliasInfo](https://msdn.microsoft.com/library/system.management.automation.aliasinfo) objects, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). -For example, use the following command: - -```powershell -Get-Member -InputObject (Get-Item Alias:*) -``` - -When you use `-InputObject`, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. - -#### Example 2 - -This command lists the values of the properties of the `dir` alias. -It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `dir` alias. -The pipeline operator `|` sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. -The [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command uses the `-Property` parameter with a wildcard character `*` to format and display the values of all the `dir` alias properties. - -```powershell -Get-Item Alias:dir | Format-List -Property * -``` - -### Changing the properties of an alias - -#### Example 1 - -You can use the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet with the `-Options` dynamic parameter to change the value of the `-Options` property of an alias. - -This command sets the **AllScope** and **ReadOnly** options for the `dir` alias. -The command uses the `-Options` dynamic parameter of the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet. -The `-Options` parameter is available in [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) only when you use it with the **Alias** or **Function** provider. - -```powershell -Set-Item -Path Alias:dir -Options "AllScope,ReadOnly" -``` - -#### Example 2 - -This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the `gp` alias so that it represents the [Get-Process](../../Microsoft.PowerShell.Management/Get-Process.md) cmdlet instead of the [Get-ItemProperty](../../Microsoft.PowerShell.Management/Get-ItemProperty.md) cmdlet. -The `-Force` parameter is required because the value of the **Options** property of the `gp` alias is set to `ReadOnly`. -Because the command is submitted from within the `Alias:` drive, the drive is not specified in the path. - -```powershell -Set-Item -Path gp -Value Get-Process -Force -``` - -The change affects the four properties that define the association between the alias and the command. -To view the effect of the change, type the following command: - -```powershell -Get-Item -Path gp | Format-List -Property * -``` - -#### Example 3 - -This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the `popd` alias to `pop`. - -```powershell -Rename-Item -Path Alias:popd -NewName pop -``` - -### Copying an alias - -#### Example 1 - -This command copies the `pushd` alias so that a new `push` alias is created for the [Push-Location](../../Microsoft.PowerShell.Management/Push-Location.md) cmdlet. - -```powershell -Copy-Item -Path Alias:pushd -Destination Alias:push -``` - -When the new alias is created, its **Description** property has a null value. -And, its **Option** property has a value of `None`. -If the command is issued from within the `Alias:` drive, you can omit the drive name from the value of the `-Path` parameter. - -### Deleting an alias - -#### Example 1 - -This command deletes the `serv` alias from the current session. -You can use this command in any PowerShell drive. - -```powershell -Remove-Item -Path Alias:serv -``` - -If you are in the `Alias:` drive, you can omit the drive name from the path. - -#### Example 2 - -This command deletes aliases that begin with "s". -It does not delete read-only aliases. - -```powershell -Clear-Item -Path Alias:s* -``` - -#### Example 3 - -This command deletes all aliases from the current session, except those with a value of `Constant` for their **Options** property. -Without the `-Force` parameter, the command does not delete aliases whose **Options** property has a value of `ReadOnly`. - -```powershell -Remove-Item Alias:* -Force -``` - -## 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. - -### `Options` [System.Management.Automation.ScopedItemOptions](https://msdn.microsoft.com/library/system.management.automation.scopeditemoptions) - -Determines the value of the **Options** property of an alias. - -|Value|Description| -|-----------|-----------------| -|`None`|No options. This value is the default.| -|`Constant`|The alias cannot be deleted and its properties cannot be changed. `Constant` is available only when you create an alias. You cannot change the option of an existing alias to `Constant`.| -|`Private`|The alias is visible only in the current scope, not in the child scopes.| -|`ReadOnly`|The properties of the alias cannot be changed except by using the `-Force` parameter. You can use [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) to delete the alias.| -|`AllScope`|The alias is copied to any new scopes that are created.| - -#### Cmdlets supported: - -- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -## See also - -[about_Aliases](../About/about_Aliases.md) - -[about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/Environment-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/Environment-Provider.md deleted file mode 100644 index f47696935cbb..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/Environment-Provider.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Environment Provider -online version: https://go.microsoft.com/fwlink/?linkid=834944 ---- - - -# *Environment* provider - - -## Provider name - - Environment - - -## Drives - - `Env:` - - -## Short description - - Provides access to the Windows environment variables. - - -## Detailed description - - The PowerShell **Environment** provider lets you get, add, change, clear, and delete Windows environment variables in PowerShell. - - The **Environment** provider is a flat namespace that contains only objects that represent the environment variables. The variables have no child items. - - Each environment variable is an instance of the [System.Collections.DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) class. The name of the variable is the dictionary key. The value of the environment variable is the dictionary value. - - The **Environment** provider exposes its data store in the `Env:` drive. To work with environment variables, change your location to the `Env:` drive (`set-location Env:`), or work from another PowerShell drive. To reference an environment variable from another location, use the `Env:` drive name in the path. - - The **Environment** provider supports all the cmdlets that contain the *Item* noun except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). And, it supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets that contain the *ItemProperty* noun, and it does not support the `-Filter` parameter in any cmdlet. - - Environment variables must conform to the usual naming standards. Additionally, the name cannot include the equal sign (`=`). - -## Capabilities - - ShouldProcess - - -## Examples - - -### Getting to the `Env:` drive - - -#### Example 1 - - This command changes the current location to the `Env:` drive: - -```powershell -Set-Location Env: -``` - - You can use this command from any drive in PowerShell. To return to a file system drive, type the drive name. For example, type: -```powershell -Set-Location c: -``` - - -### Getting environment variables - - -#### Example 1 - - This command lists all the environment variables in the current session: - -```powershell -Get-ChildItem -Path Env: -``` - - You can use this command from any PowerShell drive. - - -#### Example 2 - - This command gets the `WINDIR` environment Variable: - -```powershell -Get-ChildItem -Path Env:windir -``` - - -#### Example 3 - - This command gets a list of all the environment variables in the current session and then sorts them by name: - -```powershell -Get-ChildItem | Sort-Object -Property name -``` - - By default, the environment variables appear in the order that PowerShell discovers them. This command is submitted in the `Env:` drive. -When you run this command from another drive, add the `-Path` parameter with a value of `Env:`. - - -### Creating a new environment variable - - -#### Example 1 - - This command creates the `USERMODE` environment variable with a value of "Non-Admin": - -```powershell -New-Item -Path . -Name USERMODE -Value Non-Admin -``` - - Because the current location is in the `Env:` drive, the value of the `-Path` parameter is a dot (`.`). The dot represents the current location. -If you are not in the `Env:` drive, the value of the `-Path` parameter would be `Env:`. - - -### Displaying the properties and methods of environment variables - - -#### Example 1 - - This command uses the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet to get all the environment variables: - -```powershell -Get-ChildItem -Path Env: | Get-Member -``` - - The pipeline operator (`|`) sends the results to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), which displays the methods and properties of the object. -When you pipe a collection of objects to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), such as the collection of environment variables in the `Env:` drive, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately. [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) then returns information about each object type that it finds. If all the objects are of the same type, it returns information about the single object type. In this case, all the environment variables are [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) objects. -To get information about the collection of [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) objects, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, type: - -```powershell -Get-Member -InputObject (Get-ChildItem Env:) -``` - -When you use the `-InputObject` parameter, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. - - -#### Example 2 - - This command lists the values of the properties of the `WINDIR` environment Variable: - -```powershell -Get-Item Env:windir | Format-List -Property * -``` - - It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `WINDIR` environment variable. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. It uses the `-Property` parameter with a wildcard character (`*`) to format and display the values of all the properties of the `WINDIR` environment variable. - - -### Changing the properties of an environment variable - - -#### Example 1 - - This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `USERMODE` environment variable that you created to `USERROLE`: - -```powershell -Rename-Item -Path Env:USERMODE -NewName USERROLE -``` - - This change affects the **Name**, **Key**, and **PSPath** properties of the [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) object. -Do not change the name of an environment variable that the system uses. Although these changes affect only the current session, they might cause the system or a program to operate incorrectly. - - -#### Example 2 - - This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the value of the `USERROLE` environment variable to "Administrator": - -```powershell -Set-Item -Path Env:USERROLE -Value Administrator -``` - - -### Copying an environment variable - - -#### Example 1 - - This command copies the value of the `USERROLE` environment variable to the `USERROLE2` environment Variable: - -```powershell -Copy-Item -Path Env:USERROLE -Destination Env:USERROLE2 -``` - - -### Deleting an environment variable - - -#### Example 1 - - This command deletes the `USERROLE2` environment variable from the current session: - -```powershell -Remove-Item -Path Env:USERROLE2 -``` - - You can use this command in any PowerShell drive. If you are in the `Env:` drive, you can omit the drive name from the path. - - -#### Example 2 - - This command deletes the `USERROLE` environment variable. - -```powershell -Clear-Item -Path Env:USERROLE -``` - - -## See also - - [about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider.md deleted file mode 100644 index 9145794b4fd2..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider.md +++ /dev/null @@ -1,692 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: FileSystem Provider -online version: http://go.microsoft.com/fwlink/?LinkId=821468 ---- - - -# *FileSystem* provider - - -## Provider name - -FileSystem - - -## Drives - -`C:`, `D:` ... - - -## Short description - -Provides access to files and directories. - - -## Detailed description - -The PowerShell **FileSystem** provider lets you get, add, change, clear, and delete files and directories in PowerShell. - -The **FileSystem** provider exposes PowerShell drives that correspond to the logical drives on your computer, including drives that are mapped to network shares. This lets you reference these drives from within PowerShell. - -The **FileSystem** provider lets you refer to files and folders in PowerShell in the same way that you refer to them in Windows. - -To refer to a drive, specify the drive name followed by a colon. Like most of PowerShell, the **FileSystem** provider is not case-sensitive. For example, to get the files and folders on the "C" drive, you refer to the `C:` drive or the `c:` drive. - -A fully qualified name includes the drive name, followed by a colon `:`, any directory and subdirectory names, and the file name (when applicable). Each element of the fully qualified name must be separated either by a backslash `\` or a forward slash `/`. - -The following example shows the fully qualified name for the `Shell.dll` file in the `System32` subdirectory of the `Windows` directory on the `C` drive. - -``` -C:\Windows\System32\shell.dll -``` - -If any element in the fully qualified name includes spaces, you must enclose the name in quotation marks `" "`. For example, - -``` -"C:\Program Files\Internet Explorer\iexplore.exe" -``` - -The current location in the file system is represented by a dot or period character `.`. - -For example, the current location is the `C:\Windows\System32` directory, then you can refer to the `Shell.dll` file in that directory as the following: - -``` -.\Shell.dll -``` - -To use the **FileSystem** provider to view and manage files and folders, use the provider cmdlets, such as [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) (`dir`, `ls`) and [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) (`cd`). PowerShell also includes a `mkdir` function (alias `md`) that uses the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create a new directory. - -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](../Get-Help.md) command in a file system drive or use the `-Path` parameter of [Get-Help](../Get-Help.md) to specify a file system drive. - -For example, - -```powershell -Get-Help Get-ChildItem -``` - -or - -```powershell -Get-Help Get-ChildItem -Path c: -``` - - Also, beginning in Windows PowerShell 3.0, the **FileSystem** provider supports credentials for the `New-PSDrive`cmdlet. For more information about `New-PSDrive` cmdlet, see the help topic for the [New-PSDrive](../../Microsoft.PowerShell.Management/New-PSDrive.md) cmdlet. - - -## Capabilties - -Filter, ShouldProcess - - -## Examples - - -### Splitting a large file - - -#### Example 1 - -By default, the `Get-Content` cmdlet uses the end-of-line character as its delimiter, so it gets a file as a collection of strings, with each line as one string in the file. - -You can use the `-Delimiter` parameter to specify an alternate delimiter. If you set it to the characters that denote the end of a section or the beginning of the next section, you can split the file into logical parts. - -The first command gets the `Employees.txt` file and splits it into sections, each of which ends with the words "End of Employee Record" and it saves it in the `$e` variable. - -The second command uses array notation to get the first item in the collection in `$e`. It uses an index of 0, because PowerShell arrays are zero-based. - -For more information about `Get-Content` cmdlet, see the help topic for the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md). - -For more information about arrays, see [about_Arrays](../About/about_Arrays.md). - -```powershell -$e = Get-Content c:\test\employees.txt -Delimited "End Of Employee Record" -$e[0] -``` - - -### Navigating the file system - - -#### Example 1 - -This command gets the current location: - -```powershell -Get-Location -``` - -The [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) cmdlet includes the functionality of commands like the `cd` command in the Windows Command Prompt and the `pwd` command in UNIX. For more information, type: - -```powershell -Get-Help Get-Location -``` - - -#### Example 2 - -This command sets the current location: - -```powershell -Set-Location C: -``` - - -### Getting file and directory information - - -#### Example 1 - -This command gets all the files and directories in the current directory: - -```powershell -Get-ChildItem -``` - -By default, the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet does not recurse. If files and folders are present in the current directory when you run this command, a [System.IO.FileInfo](https://msdn.microsoft.com/library/system.io.fileinfo) object and a [System.IO.DirectoryInfo](https://msdn.microsoft.com/library/system.io.directoryinfo) object are returned. - - -#### Example 2 - -This command gets all the files in the current directory: - -```powershell -Get-ChildItem | Where-Object {!$_.psiscontainer} -``` - -The command uses the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet to get all files and directories. It pipes the results to the [Where-Object](../Where-Object.md) cmdlet, which selects only the objects that are not (`!`) containers. - - -#### Example 3 - -The command uses the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet to get all files and directories. It pipes the results to [Where-Object](../Where-Object.md), which select only the objects that are containers. - -```powershell -Get-ChildItem | Where-Object {$_.psiscontainer} -``` - - -#### Example 4 - -This command displays the properties of a directory: - -```powershell -Get-Item -Path c:\ps-test | Format-List -Property * -``` - -The command uses the **Path** parameter of the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get the `C:\ps-test` directory. It pipes the directory object to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) cmdlet, which displays all (`*`) the properties and values of the directory in a list. - - -#### Example 5 - -This command displays the properties of a file: - -```powershell -Get-Item -Path test.txt | Format-List -Property * -``` - -The command uses the **Path** parameter of the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get the `test.txt` file. It pipes the file object to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) cmdlet, which displays all (`*`) the properties and values of the file in a list. - - -### Copying files and directories - - -#### Example 1 - -This command copies the `a.txt` file from the `C:\a` directory to the `C:\a\bb` directory: - -```powershell -Copy-Item -Path C:\a\a.txt -Destination C:\a\bb\a.txt -``` - -It overwrites files in the destination directory without prompting for confirmation. - - -#### Example 2 - -This command copies all the files in the `C:\a\bb` directory that have the `.txt` file name extension to the `C:\a\cc\ccc\` directory: - -```powershell -Copy-Item -Path C:\a\bb\*.txt -Destination C:\a\cc\ccc\ -``` - -It uses the original names of the files. The command overwrites the existing files in the destination directory without prompting for confirmation. - - -#### Example 3 - -Copies all the directories and files in the `C:\a` directory to the `C:\c` directory. If any of the directories to copy already exist in the destination directory, the command will fail unless you specify the Force parameter. - -```powershell -Copy-Item -Path C:\a\* -Destination C:\c -Recurse -``` - - -### Moving files and directories - - -#### Example 1 - -This command moves the `c.txt` file in the `C:\a` directory to the `C:\a\aa` directory: - -```powershell -Move-Item -Path C:\a\c.txt -Destination C:\a\aa -``` - -The command will not automatically overwrite an existing file that has the same name. To force the cmdlet to overwrite an existing file, specify the Force parameter. - - -#### Example 2 - -This command moves the `C:\a` directory and all its contents to the `C:\b` directory: - -```powershell -Move-Item -Path C:\a -Destination C:\b -``` - -You cannot move a directory when that directory is the current location. - - -### Managing file content - - -#### Example 1 - -This command appends the "test content" string to the `Test.txt` file: - -```powershell -Add-Content -Path test.txt -Value "test content" -``` - -The existing content in the `Test.txt` file is not deleted. - - -#### Example 2 - -This command gets the contents of the `Test.txt` file and displays them in the console: - -```powershell -Get-Content -Path test.txt -``` - -You can pipe the contents of the file to another cmdlet. For example, the following command reads the contents of the `Test.txt` file and then supplies them as input to the [ConvertTo-Html](../../Microsoft.PowerShell.Utility/ConvertTo-Html.md) cmdlet: - -```powershell -Get-Content -Path test.txt | ConvertTo-Html -``` - - -#### Example 3 - -This command replaces the contents of the `Test.txt` file with the "test content" string: - -```powershell -Set-Content -Path test.txt -Value "test content" -``` - -It overwrites the contents of `Test.txt`. You can use the **Value** parameter of the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to add content to a file when you create it. - - -### Managing security descriptors - - -#### Example 1 - -This command returns a [System.Security.AccessControl.FileSecurity](https://msdn.microsoft.com/library/system.security.accesscontrol.filesecurity) object: - -```powershell -Get-Acl -Path test.txt | Format-List -Property * -``` - -For more information about this object, pipe the command to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet. Or, see "[FileSecurity](http://go.microsoft.com/fwlink/?LinkId=145718) Class" in the MSDN (Microsoft Developer Network) library. - - -#### Example 2 - -This command returns a [System.Security.AccessControl.DirectorySecurity](https://msdn.microsoft.com/library/system.security.accesscontrol.directorysecurity) object: - -```powershell -Get-Acl -Path test_directory | Format-List -Property * -``` - -For more information about this object, pipe the command to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet. Or, see "[DirectorySecurity](http://go.microsoft.com/fwlink/?LinkId=145736) Class" in the MSDN library. - - -### Creating files and directories - - -#### Example 1 - -This command creates the `logfiles` directory on the `C` drive: - -```powershell -New-Item -Path c:\ -Name logfiles -Type directory -``` - - -#### Example 2 - -This command creates the `log2.txt` file in the `C:\logfiles` directory and then adds the "test log" string to the file: - -```powershell -New-Item -Path c:\logfiles -Name log2.txt -Type file -``` - - -#### Example 3 - -Creates a file called `log2.txt` in the `C:\logfiles` directory and adds the string "test log" to the file. - -```powershell -New-Item -Path c:\logfiles -Name log2.txt -Type file -Value "test log" -``` - - -### Renaming files and directories - - -#### Example 1 - -This command renames the `a.txt` file in the `C:\a` directory to `b.txt`: - -```powershell -Rename-Item -Path c:\a\a.txt -NewName b.txt -``` - - -#### Example 2 - -This command renames the `C:\a\cc` directory to `C:\a\dd`: - -```powershell -Rename-Item -Path c:\a\cc -NewName dd -``` - - -### Deleting files and directories - - -#### Example 1 - -This command deletes the `Test.txt` file in the current directory: - -```powershell -Remove-Item -Path test.txt -``` - - -#### Example 2 - -This command deletes all the files in the current directory that have the `.xml` file name extension: - -```powershell -Remove-Item -Path *.xml -``` - - -### Starting a program by invoking an associated file - - -#### Example 1 - -The first command uses the [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) cmdlet to get information about local services. - -It pipes the information to the [Export-Csv](../../Microsoft.PowerShell.Utility/Export-Csv.md) cmdlet and then stores that information in the `Services.csv` file. - -The second command uses [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) to open the `services.csv` file in the program associated with the `.csv` extension: - -```powershell -Get-Service | Export-Csv -Path services.csv -Invoke-Item -Path services.csv -``` - - -### Getting files and folders with specified attributes - - -#### Example 1 - -This command gets system files in the current directory and its subdirectories. - -It uses the `-File` parameter to get only files (not directories) and the `-System` parameter to get only items with the "system" attribute. - -It uses the `-Recurse` parameter to get the items in the current directory and all subdirectories. - -```powershell -Get-ChildItem -File -System -Recurse -``` - - -#### Example 2 - -This command gets all files, including hidden files, in the current directory. - -It uses the **Attributes** parameter with two values, `!Directory+Hidden`, which gets hidden files, and `!Directory`, which gets all other files. - -```powershell -Get-ChildItem -Attributes !Directory,!Directory+Hidden -``` - -`dir -att !d,!d+h` is the equivalent of this command. - - -#### Example 3 - -This command gets files in the current directory that are either compressed or encrypted. - -It uses the `-Attributes` parameter with two values, `Compressed` and `Encrypted`. The values are separated by a comma `,` which represents the "OR" operator. - -```powershell -Get-ChildItem -Attributes Compressed,Encrypted -``` - - -## 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. - - -### `Encoding` <[Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding](https://msdn.microsoft.com/library/microsoft.powershell.commands.filesystemcmdletproviderencoding)> - -Specifies the file encoding. The default is ASCII. - -|Value|Description| -|-----------|-----------------| -|`Unknown`|The encoding type is unknown or invalid. The data can be treated as binary.| -|`String`|Uses the encoding type for a string.| -|`Unicode`|Encodes in UTF-16 format using the little-endian byte order.| -|`Byte`|Encodes a set of characters into a sequence of bytes.| -|`BigEndianUnicode`|Encodes in UTF-16 format using the big-endian byte order.| -|`UTF8`|Encodes in UTF-8 format.| -|`UTF7`|Encodes in UTF-7 format.| -|`ASCII`|Uses the encoding for the ASCII (7-bit) character set.| - - -#### Cmdlets supported: - - -- [Add-Content](../../Microsoft.PowerShell.Management/Add-Content.md) - -- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) - -- [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) - - -### `Delimiter` <[System.String](https://msdn.microsoft.com/library/system.string)> - -Specifies the delimiter that [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) uses to divide the file into objects while it reads. - -The default is `\n`, the end-of-line character. - -Therefore, by default, when reading a text file, [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) returns a collection of string objects, each of which ends with an end-of-line character. - -When you enter a delimiter that does not exist in the file, [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) returns the entire file as a single, undelimited object. - -You can use this parameter to split a large file into smaller files by specifying a file separator, such as "End of Example", as the delimiter. The delimiter is preserved (not discarded) and becomes the last item in each file section. - -***Troubleshooting Note***: Currently, when the value of the `-Delimiter` parameter is an empty string, [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) does not return anything. This is a known issue. To force [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) to return the entire file as a single, undelimited string, enter a value that does not exist in the file. - - -#### Cmdlets supported: - - -- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) - - -### `Wait` <[System.Management.Automation.SwitchParameter](https://msdn.microsoft.com/library/system.management.automation.switchparameter)> - -Waits for content to be appended to the file. If content is appended, it returns the appended content. If the content has changed, it returns the entire file. - -When waiting, [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) checks the file once each second until you interrupt it, such as by pressing CTRL+C. - - -#### Cmdlets supported: - - -- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) - - -### `Attributes` <[FlagsExpression](https://msdn.microsoft.com/library/hh485401)([System.IO.FileAttributes](https://msdn.microsoft.com/library/system.io.fileattributes))> - -Gets files and folders with the specified attributes. This parameter supports all attributes and lets you specify complex combinations of attributes. - -The `-Attributes` parameter was introduced in Windows PowerShell 3.0. - -The `-Attributes` parameter supports the following attributes: - -- `Archive` -- `Compressed` -- `Device` -- `Directory` -- `Encrypted` -- `Hidden` -- `Normal` -- `NotContentIndexed` -- `Offline` -- `ReadOnly` -- `ReparsePoint` -- `SparseFile` -- `System` -- `Temporary` - -For a description of these attributes, see the [FileAttributes](http://go.microsoft.com/fwlink/?LinkId=201508) enumeration. - -Use the following operators to combine attributes. - -- `!` NOT -- `+` AND -- `,` OR - -No spaces are permitted between an operator and its attribute. However, spaces are permitted before commas. - - -#### Cmdlets supported: - - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - - -### `Directory` <[System.Management.Automation.SwitchParameter](https://msdn.microsoft.com/library/system.management.automation.switchparameter)> - -Gets directories (folders). - -The `-Directory` parameter was introduced in Windows PowerShell 3.0. - -To get only directories, use the `-Directory` parameter and omit the `-File` parameter. To exclude directories, use the `-File` parameter and omit the `-Directory` parameter, or use the `-Attributes` parameter. - - -#### Cmdlets supported: - - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - - -### `File` <[System.Management.Automation.SwitchParameter](https://msdn.microsoft.com/library/system.management.automation.switchparameter)> - -Gets files. - -The `-File` parameter was introduced in Windows PowerShell 3.0. - -To get only files, use the `-File` parameter and omit the `-Directory` parameter. To exclude files, use the `-Directory` parameter and omit the `-File` parameter, or use the `-Attributes` parameter. - - -#### Cmdlets supported: - - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - - -### `Hidden` <[System.Management.Automation.SwitchParameter](https://msdn.microsoft.com/library/system.management.automation.switchparameter)> - -Gets only hidden files and directories (folders). By default, [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets only non-hidden items. - -The `-Hidden` parameter was introduced in Windows PowerShell 3.0. - -To get only hidden items, use the `-Hidden` parameter, its `h` or `ah` aliases, or the **Hidden** value of the `-Attributes` parameter. To exclude hidden items, omit the `-Hidden` parameter or use the `-Attributes` parameter. - - -#### Cmdlets supported: - - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - - -### `ReadOnly` <[System.Management.Automation.SwitchParameter](https://msdn.microsoft.com/library/system.management.automation.switchparameter)> - -Gets only read-only files and directories (folders). - -The `-ReadOnly` parameter was introduced in Windows PowerShell 3.0. - -To get only read-only items, use the `-ReadOnly` parameter, its `ar` alias, or the **ReadOnly** value of the `-Attributes` parameter. To exclude read-only items, use the `-Attributes` parameter. - - -#### Cmdlets supported: - - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - - -### `System` <[System.Management.Automation.SwitchParameter](https://msdn.microsoft.com/library/system.management.automation.switchparameter)> - -Gets only system files and directories (folders). - -The `-System` parameter was introduced in Windows PowerShell 3.0. - -To get only system files and folders, use the `-System` parameter, its `as` alias, or the **System** value of the `-Attributes` parameter. To exclude system files and folders, use the `-Attributes` parameter. - - -#### Cmdlets supported: - - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - - -### `NewerThan` <[System.DateTime](https://msdn.microsoft.com/library/system.datetime)> - - -Returns `$True` when the `LastWriteTime` value of a file is greater than the specified date. Otherwise, it returns `$False`. - -Enter a [DateTime](https://msdn.microsoft.com/library/system.datetime) object, such as one that the [Get-Date](../../Microsoft.PowerShell.Utility/Get-Date.md) cmdlet returns, or a string that can be converted to a [DateTime](https://msdn.microsoft.com/library/system.datetime) object, such as `"August 10, 2011 2:00 PM"`. - - -#### Cmdlets supported: - - -- [Test-Path](../../Microsoft.PowerShell.Management/Test-Path.md) - - -### `OlderThan` <[System.DateTime](https://msdn.microsoft.com/library/system.datetime)> - -Returns `$True` when the `LastWriteTime` value of a file is less than the specified date. Otherwise, it returns `$False`. - -Enter a [DateTime](https://msdn.microsoft.com/library/system.datetime) object, such as one that the [Get-Date](../../Microsoft.PowerShell.Utility/Get-Date.md) cmdlet returns, or a string that can be converted to a [DateTime](https://msdn.microsoft.com/library/system.datetime) object, such as `"August 10, 2011 2:00 PM"`. - - -#### Cmdlets supported: - - -- [Test-Path](../../Microsoft.PowerShell.Management/Test-Path.md) - - -### `Stream` <[System.String](https://msdn.microsoft.com/library/system.string)[]> - -Manages alternate data streams. Enter the stream name. Wildcards are permitted only in [Get-Item for FileSystem](FileSystem-Provider/Get-Item-for-FileSystem.md) and [Remove-Item for FileSystem](FileSystem-Provider/Remove-Item-for-FileSystem.md) commands in a file system drive. - - -#### Cmdlets supported: - - -- [Add-Content](../../Microsoft.PowerShell.Management/Add-Content.md) - -- [Clear-Content](../../Microsoft.PowerShell.Management/Clear-Content.md) - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) - -- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - -- [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) - - -### `Raw` <[SwitchParameter](https://msdn.microsoft.com/library/system.management.automation.switchparameter)> - - -Ignores newline characters. Returns contents as a single item. - - -#### Cmdlets supported: - - -- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) - - -## See also - - -[about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Add-Content-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Add-Content-for-FileSystem.md deleted file mode 100644 index a01498580851..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Add-Content-for-FileSystem.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Add-Content for FileSystem -online version: http://go.microsoft.com/fwlink/?LinkId=834948 ---- - -# Add-Content for FileSystem -Appends content, such as words or data, to a file. - -## Syntax - -``` -Add-Content [-Encoding { | | | | | | | | | | }] [-Force] [-Stream ] [-Confirm] [-WhatIf] [] - -``` - -## Description - In file system drives, the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet appends the content you specify to the end of a file. This cmdlet is not valid on folders. - - Note: This custom cmdlet help file explains how the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet works in a file system drive. For information about the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) -Path $null" or see [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) at http://go.microsoft.com/fwlink/?LinkID=113278. - -## Parameters - -### -Encoding - Specifies the file encoding. The default is ASCII. - - Valid values are: - - -- ASCII: Uses the encoding for the ASCII (7-bit) character set. - - -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. - - -- Byte: Encodes a set of characters into a sequence of bytes. - - -- String: Uses the encoding type for a string. - - -- Unicode: Encodes in UTF-16 format using the little-endian byte order. - - -- UTF7: Encodes in UTF-7 format. - - -- UTF8: Encodes in UTF-8 format. - - -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. - - Encoding is a dynamic parameter that the FileSystem provider adds to the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet. This parameter works only in file system drives. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|ASCII| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Force - Adds contents to files even if they are read-only. Without this parameter, read-only files are not affected. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|False| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Stream - Adds the content to the specified alternate data stream. If the stream does not yet, exist, [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) creates it. Enter the stream name. Wildcards are not supported. - - Stream is a dynamic parameter that the FileSystem provider adds to the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet. This parameter works only in file system drives. - - This parameter is introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|Sytem.Object[], System.String[], System.Management.Automation.PSCredential

You can pipe the value (object), a path, or a credential object to Add-Contnet.| -|Outputs|None or System.String

When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.| - -## Example 1 - -``` -C:\PS>Add-Content -Path *.txt -Exclude help* -Value "END" - -Description ------------ -This command adds "END" to all text files in the current directory, except for those with file names that begin with "help." - -``` - -## Example 2 - -``` -C:\PS>Add-Content -Path file1.log, file2.log -Value (get-date) -PassThru - -Description ------------ -This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. - -The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. The PassThru parameter sends the added content through the pipeline. Because there is no other cmdlet to receive the passed content, it is displayed at the command line. - -``` - -## Example 3 - -``` -C:\PS>Add-Content -Path monthly.txt -Value (Get-Content c:\rec1\weekly.txt) - -Description ------------ -This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to Add-Content. The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. - -You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. In that case, the command would be "add-content -path monthly.txt -value $w". - -``` - -## Example 4 - -``` -C:\PS>Add-Content -Value (Get-Content test.log) -Path C:\tests\test134\logs\test134.log - -Description ------------ -This command creates a new directory and file and copies the content of an existing file to the newly created file. - -This command uses the Add-Content cmdlet to add the content. The value of the Value parameter is a Get-Content command that gets content from an existing file, Test.log. - -The value of the path parameter is a path that does not exist when the command runs. In this example, only the C:\Tests directories exist. The command creates the remaining directories and the Test134.log file. - -The Force parameter is not required for this command. Add-Content creates directories to complete a path even without the Force parameter. - -``` - -## Example 5 - -``` -C:\PS>Get-Content test.xml | Add-Content final.xml -Force -Encoding UTF8 - -Description ------------ -This command appends the contents of the final.xml file to the contents of the test.xml file. - -The command uses the Force parameter so that the command is successful even if the Final.xml file is read-only. It uses the Encoding parameter to specify an encoding of UTF-8. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) - [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Clear-Content-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Clear-Content-for-FileSystem.md deleted file mode 100644 index f475d605759e..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Clear-Content-for-FileSystem.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Clear-Content for FileSystem -online version: http://go.microsoft.com/fwlink/?LinkId=834949 ---- - -# Clear-Content for FileSystem -Deletes the contents of an item, but does not delete the item. - -## Syntax - -``` -Clear-Content [-Stream ] [] - -``` - -## Description - In the file system, [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) clears the content in a file, but does not delete the file. It has no effect on folders. - - Note: This custom cmdlet help file explains how the [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) cmdlet works in a file system drive. For information about the [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) -Path $null" or see [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) at http://go.microsoft.com/fwlink/?LinkID=113282. - -## Parameters - -### -Stream - Deletes the content in the specified alternate data stream, but does not delete the alternate data stream. Enter the stream name. Wildcards are not supported. - - Stream is a dynamic parameter that the FileSystem provider adds to the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet. This parameter works only in file system drives. - - You can use the [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) cmdlet to clear the content of an alternate data stream. However, it is not the recommended way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. - - This parameter is introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|| -|Outputs|| - -## Example 1 - -``` -C:\PS>Get-Content C:\Test\Copy-Script.ps1 -Stream Zone.Identifier - -[ZoneTransfer] -ZoneId=3 - -C:\PS>Clear-Content C:\Test\Copy-Script.ps1 -Stream Zone.Identifier - -C:\PS>Get-Content C:\Test\Copy-Script.ps1 -Stream Zone.Identifier -C:\PS> - -Description ------------ -This example shows how the Clear-Content cmdlet clears the content from an alternate data stream while leaving the stream intact. - -The first command uses the Get-Content cmdlet to get the content of the Zone.Identifier stream in the Copy-Script.ps1 file, which was downloaded from the Internet. - -The second command uses the Clear-Content cmdlet to clear the content. - -The third command repeats the first command. It verifies that the content is cleared, but the stream remains. If the stream were deleted, the command would generate an error. - -You can use a method like this one to clear the content of an alternate data stream. However, it is not the recommended way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. - -``` - -## Example 2 - -``` -C:\PS>Clear-Content ..\SmpUsers\*\init.txt - -Description ------------ -This command deletes all of the content from the "init.txt" files in all subdirectories of the SmpUsers directory. The files are not deleted, but they are empty. - -``` - -## Example 3 - -``` -C:\PS>Clear-Content -Path * -Filter *.log -Force - -Description ------------ -This command deletes the contents of all files in the current directory with the ".log" file name extension, including files with the read-only attribute. The asterisk (*) in the path represents all items in the current directory. The Force parameter makes the command effective on read-only files. Using a filter to restrict the command to files with the ".log" file name extension instead of specifying "*.log" in the path makes the operation faster. - -``` - -## Example 4 - -``` -C:\PS>Clear-Content c:\Temp\* -Include Smp* -Exclude *2* -WhatIf - -Description ------------ -This command requests a prediction of what would happen if you submitted the command: "clear-content c:\temp\* -include smp* -exclude *2*". The result lists the files that would be cleared; in this case, files in the Temp directory whose names begin with "Smp", unless the file names include a "2". To execute the command, run it again without the Whatif parameter. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) - [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-ChildItem-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-ChildItem-for-FileSystem.md deleted file mode 100644 index a4876b1d2695..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-ChildItem-for-FileSystem.md +++ /dev/null @@ -1,281 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Get-ChildItem for FileSystem -online version: http://go.microsoft.com/fwlink/?LinkId=834950 ---- - -# Get-ChildItem for FileSystem -Gets the files and folders in a file system drive. - -## Syntax - -``` -Get-ChildItem [-Attributes ] [-Directory] [-File] [-Force] [-Hidden] [-ReadOnly] [-System] [] - -``` - -## Description - In a file system drive, the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet gets the directories, subdirectories, and files. In a file system directory, it gets subdirectories and files. - - By default, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets non-hidden items, but you can use the Directory, File, Hidden, ReadOnly, and System parameters to get only items with these attributes. To create a complex attribute search, use the Attributes parameter. If you use these parameters, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets only the items that meet all search conditions, as though the parameters were connected by an AND operator. - - Note: This custom cmdlet help file explains how the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet works in a file system drive. For information about the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) -Path $null" or see [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) at http://go.microsoft.com/fwlink/?LinkID=113308. - -## Parameters - -### -Attributes - Gets files and folders with the specified attributes. This parameter supports all attributes and lets you specify complex combinations of attributes. - - For example, to get non-system files (not directories) that are encrypted or compressed, type: - - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) -Attributes !Directory+!System+Encrypted, !Directory+!System+Compressed - - To find files and folders with commonly used attributes, you can use the Attributes parameter, or the Directory, File, Hidden, ReadOnly, and System switch parameters. - - The Attributes parameter supports the following attributes: Archive, Compressed, Device, Directory, Encrypted, Hidden, Normal, NotContentIndexed, Offline, ReadOnly, ReparsePoint, SparseFile, System, and Temporary. For a description of these attributes, see the FileAttributes enumeration at http://go.microsoft.com/fwlink/?LinkId=201508. - - Use the following operators to combine attributes. - - ! NOT - - \+ AND - - , OR - - No spaces are permitted between an operator and its attribute. However, spaces are permitted before commas. - - You can use the following abbreviations for commonly used attributes: - - D Directory - - H Hidden - - R Read-only - - S System - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Directory - Gets directories (folders). - - To get only directories, use the Directory parameter and omit the File parameter. To exclude directories, use the File parameter and omit the Directory parameter, or use the Attributes parameter. - - To get directories, use the Directory parameter, its "ad" alias, or the Directory attribute of the Attributes parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|None| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -File - Gets files. - - To get only files, use the File parameter and omit the Directory parameter. To exclude files, use the Directory parameter and omit the File parameter, or use the Attributes parameter. - - To get files, use the File parameter, its "af" alias, or the File value of the Attributes parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Hidden - Gets only hidden files and directories (folders). By default, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets only non-hidden items, but you can use the Force parameter to include hidden items in the results. - - To get only hidden items, use the Hidden parameter, its "h" or "ah" aliases, or the Hidden value of the Attributes parameter. To exclude hidden items, omit the Hidden parameter or use the Attributes parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -ReadOnly - Gets only read-only files and directories (folders). - - To get only read-only items, use the ReadOnly parameter, its "ar" alias, or the ReadOnly value of the Attributes parameter. To exclude read-only items, use the Attributes parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -System - Gets only system files and directories (folders). - - To get only system files and folders, use the System parameter, its "as" alias, or the System value of the Attributes parameter. To exclude system files and folders, use the Attributes parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Force - Gets hidden files and folders. By default, hidden files and folder are excluded. You can also get hidden files and folders by using the Hidden parameter or the Hidden value of the Attributes parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.String[]

You can pipe a file system path (in quotation marks) to Get-ChildItem.| -|Outputs|System.IO.DirectoryInfo, System.IO.FileInfo, System.String| - -## Notes - The Attributes, Directory, File, Hidden, ReadOnly, and System parameters were introduced in Windows PowerShell 3.0 and - - are effective only in file system drives. - - Get-ChildItem Alias Reference: - - --------------------------------\- - - Get-ChildItem dir - - Directory d, ad - - File af - - Hidden h, ah - - ReadOnly ar - - System as - -## Example 1 - -``` -C:\PS>Get-ChildItem - -Description ------------ -This command gets the files and subdirectories in the current directory. If the current directory does not have child items, the command does not return any results. - -``` - -## Example 2 - -``` -C:\PS>Get-Childitem -System -File -Recurse - -Description ------------ -This command gets system files in the current directory and its subdirectories. - -``` - -## Example 3 - -``` -C:\PS>Get-ChildItem -Attributes !Directory,!Directory+Hidden - -C:\PS> dir -att !d,!d+h - -Description ------------ -These command get all files, including hidden files, in the current directory, but exclude subdirectories. The second command uses aliases and abbreviations, but has the same effect as the first. - -``` - -## Example 4 - -``` -C:\PS>dir -ad - -Description ------------ -This command gets the subdirectories in the current directory. It uses the "dir" alias of the Get-ChildItem cmdlet and the "ad" alias of the Directory parameter. - -``` - -## Example 5 - -``` -C:\PS>Get-ChildItem -File -Attributes !ReadOnly -path C:\ps-test - -Description ------------ -This command gets read-write files in the C:\ps-test directory. - -``` - -## Example 6 - -``` -C:\PS>get-childitem . -include *.txt -recurse -force - -Description ------------ -This command gets all of the .txt files in the current directory and its subdirectories. - -The dot (.) represents the current directory. The Include parameter specifies the file name extension. The Recurse parameter directs PowerShell to search for objects recursively, and it indicates that the subject of the command is the specified directory and its contents. The Force parameter adds hidden files to the display. - -``` - -## Example 7 - -``` -C:\PS>get-childitem c:\windows\logs\* -include *.txt -exclude A* - -Description ------------ -This command gets the .txt files in the Logs subdirectory, except for those whose names start with the letter A. It uses the wildcard character (*) to indicate the contents of the Logs subdirectory, not the directory container. Because the command does not include the Recurse parameter, Get-ChildItem does not include the contents of the current directory automatically; you need to specify it. - -``` - -## Example 8 - -``` -C:\PS>get-childitem -name - -Description ------------ -This command retrieves only the names of items in the current directory. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) - [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-Content-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-Content-for-FileSystem.md deleted file mode 100644 index ac3ffc54a4bf..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-Content-for-FileSystem.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Get-Content for FileSystem -online version: http://go.microsoft.com/fwlink/?LinkId=834951 ---- - -# Get-Content for FileSystem -Gets the contents of a file. - -## Syntax - -``` -Get-Content [-Delimiter ] [-Encoding { | | | | | | | | | | }] [-Force] [-Raw ] [-Stream ] [-Wait] [] - -``` - -## Description - In file system drives, you can use the [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) cmdlet to get content that you display at the command line, save in a variable for processing, or write to another file. It is not valid on folders. - - Note: This custom cmdlet help file explains how the [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) cmdlet works in a file system drive. For information about the [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) -Path $null" or see [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) at http://go.microsoft.com/fwlink/?LinkID=113310. - -## Parameters - -### -Encoding - Specifies the file encoding. The default is ASCII. - - Valid values are: - - -- ASCII: Uses the encoding for the ASCII (7-bit) character set. - - -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. - - -- Byte: Encodes a set of characters into a sequence of bytes. - - -- String: Uses the encoding type for a string. - - -- Unicode: Encodes in UTF-16 format using the little-endian byte order. - - -- UTF7: Encodes in UTF-7 format. - - -- UTF8: Encodes in UTF-8 format. - - -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. - - Encoding is a dynamic parameter that the FileSystem provider adds to the [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) cmdlet. This parameter works only in file system drives. - - When reading from and writing to binary files, use a value of Byte for the Encoding dynamic parameter and a value of 0 for the ReadCount parameter. A ReadCount value of 0 reads the entire file in a single read operation and converts it into a single object (PSObject). The default ReadCount value, 1, reads one byte in each read operation and converts each byte into a separate object, which causes errors when you use the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet to write the bytes to a file. For more information, see the examples. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|ASCII| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Delimiter - Specifies the delimiter that [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) uses to divide the file into objects while it reads. - - The default is "\n", the end-of-line character. - - Therefore, by default, when reading a text file, [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) returns a collection of string objects, each of which ends with an end-of-line character. - - When you enter a delimiter that does not exist in the file, [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) returns the entire file as a single, undelimited object. - - You can use this parameter to split a large file into smaller files by specifying a file separator, such as "End of Example", as the delimiter. The delimiter is preserved (not discarded) and becomes the last item in each file section. - - Delimiter is a dynamic parameter that the FileSystem provider adds to the [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) cmdlet. This parameter works only in file system drives. - - Troubleshooting Note: Currently, when the value of the Delimiter parameter is an empty string, [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) does not return anything. This is a known issue. To force [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) to return the entire file as a single, undelimited string, enter a value that does not exist in the file. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|End-of-line character| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Force - Gets the contents of all files, including hidden files. By default, [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) does not get the contents of hidden files unless you specify the hidden file by name. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|False| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Raw - Ignores newline characters and returns the entire contents of a file in one string. By default, the contents of a file is returned as a array of strings that is delimited by the newline character. - - Raw is a dynamic parameter that the FileSystem provider adds to the [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) cmdlet. This parameter works only in file system drives. - - This parameter is introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Wait - Waits for the cmdlet to get the content before returning the command prompt. While waiting, [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) checks the file once each second until you interrupt it, such as by pressing CTRL+C. - - Wait is a dynamic parameter that the FileSystem provider adds to the [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) cmdlet. This parameter works only in file system drives. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|False| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Stream - Gets the contents of the specified alternate NTFS file stream from the file. Enter the stream name. Wildcards are not supported. - - Stream is a dynamic parameter that the FileSystem provider adds to the [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) cmdlet. This parameter works only in file system drives. - - This parameter is introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.Int64, System.String[], System.Management.Automation.PSCredential

You can pipe the read count, total count, paths, or credentials to Get-Content.| -|Outputs|System.Object, System.String

Get-Content returns objects that represent the content that it gets. The object type depends on the content type. If you use the Stream parameter, the cmdlet returns the alternate data stream contents as a string.| - -## Example 1 - -``` -C:\PS>Get-Content -Path C:\Chapters\chapter1.txt - -Description ------------ -This command gets the content of the Chapter1.txt file and displays it in the console. It uses the Path parameter to specify the name of the item. - -Get-Content actually passes the content down the pipeline, but because there are no other cmdlets in the pipeline, PowerShell formats the contents and displays it in the console. - -``` - -## Example 2 - -``` -C:\PS>Get-Content C:\Logs\Log060912.txt -TotalCount 50 | Set-Content Sample.txt - -Description ------------ -This command gets the first 50 lines of the Log060912.txt file and stores them in the sample.txt file. - -The command uses the Get-Content cmdlet to get the text in the file. (The name of Path parameter, which is optional, is omitted.) The TotalCount parameter limits the retrieval to the first 50 lines. The pipeline operator (|) sends the result to Set-Content, which places it in the sample.txt file. - -``` - -## Example 3 - -``` -C:\PS>(Get-Content Cmdlets.txt -TotalCount 5)[-1] - -Description ------------ -This command gets the fifth line of the Cmdlets.txt text file. It uses the TotalCount parameter to get the first five lines and then uses array notation to get the last line (indicated by "-1") of the resulting set. - -``` - -## Example 4 - -``` -C:\PS>Get-Content .\DataSets\*.csv -Delimiter "*---*" -Force -Encoding UTF8 - -Description ------------ -This command gets the contents of all CSV files in the DataSets subdirectory. It uses the Force parameter to get all files, including hidden files, and the Encoding parameter to specify the file encoding. - -The command also uses the Delimiter parameter to divide the returned content into sets, each of which ends at the CSV file row that contains the "*----*" marker. - -``` - -## Example 5 - -``` -C:\PS>Get-Content .\Copy-Scripts.ps1 -Stream Zone.Identifier - -[ZoneTransfer] -ZoneId=3 - -Description ------------ -This command uses the Stream parameter to get the content of the Zone.Identifier alternate data stream. The output includes Zone ID value of 3, which represents the Internet. - -The Stream parameter is introduced in Windows PowerShell 3.0. - -``` - -## Example 6 - -``` -C:\PS>$Manifest = (Get-Module -List PSScheduledJob).Path - -C:\PS>$Hash = Invoke-Expression (Get-Content $Manifest -Raw) - -C:\PS>$Hash - -Name Value ----- ----- -Copyright ? Microsoft Corporation. All rights reserved. -ModuleToProcess Microsoft.PowerShell.ScheduledJob.dll -FormatsToProcess PSScheduledJob.Format.ps1xml -PowerShellVersion 3.0 -CompanyName Microsoft Corporation -GUID 50cdb55f-5ab7-489f-9e94-4ec21ff51e59 -Author Microsoft Corporation -CLRVersion 4.0 -CmdletsToExport {New-JobTrigger, Add-JobTrigger, Remove-JobTrigger, Get-JobTrigger...} -TypesToProcess PSScheduledJob.types.ps1xml -HelpInfoURI http://go.microsoft.com/fwlink/?LinkID=223911 -ModuleVersion 1.0.0.0 - -C:\PS>$Hash.ModuleToProcess -Microsoft.PowerShell.ScheduledJob.dll - -Description ------------ -The commands in this example get the contents of a module manifest file (.psd1) as a hash table. The manifest file contains a hash table, but if you get the contents without the Raw dynamic parameter, it is returned as an array of newline-delimited strings. - -The Raw dynamic parameter is introduced in Windows PowerShell 3.0. - -The first command uses the Path property of modules to get the path to the file that contains the module manifest for the PSScheduledJob module. It saves the path in the $Manifest variable. - -The second command uses the Invoke-Expression cmdlet to run a Get-Content command and the Raw dynamic parameter of the Get-Content cmdlet to get the contents of the module manifest file in a single string. The command saves the hash table in the $Hash variable. - -The third command gets the hash table in the Hash variable. The contents is returned as a collection of name-value pairs. - -The fourth command uses the ModuleToProcess property of the hash table to get the value of the ModuleToProcess key in the module manifest. - -``` - -## Example 7 - -``` -C:\PS>$a = Get-Content -Path .\Download.zip -Encoding Byte -ReadCount 0 - -Set-Content -Path \\Server\Share\Download.zip -Encoding Byte -Value $a - -$b = Get-Content -Path .\Download.zip -Encoding Byte -Set-Content -Path \\Server\Share\Download.zip -Encoding Byte -Value $b - -Set-Content : Cannot proceed with byte encoding. When using byte encoding the content must be of type byte. -At line:1 char:1 -+ Set-Content \\Server\Share\Download.zip -Encoding Byte -Value $b -+ [!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()]~~~~~ - + CategoryInfo : InvalidArgument: (:) [Set-Content], PSArgumentException - + FullyQualifiedErrorId : Argument,Microsoft.PowerShell.Commands.SetContentCommand - -Description ------------ -This example shows how to use the ReadCount parameter of the Get-Content cmdlet with a value of 0 to avoid byte-related errors when using the Set-Content cmdlet to write the bytes to a file. - -When getting the content of a file in bytes, Get-Content creates an object (PSObject) for the bytes in each read operation. If you read the bytes one at a time, which is the default, Get-Content creates an object for each byte. The objects cause errors when you use the Set-Content cmdlet to write the bytes to a file. - -The first command uses the Get-Content cmdlet to get the contents of the Download.zip file and save it in the $a variable. The command uses the Encoding dynamic parameter with a value of Byte. It also uses the ReadCount parameter with a value of 0, which directs Get-Content to get the file contents in a single read operation. The default value of the ReadCount parameter, 1, gets one byte at a time. - -The second command uses the Set-Content cmdlet to write the bytes in the $a variable to the Download.zip file on a file share. The command succeeds. - -The third and fourth commands show the same sequence without the ReadCount parameter. - -The third command uses the Encoding dynamic parameter of the Get-Content cmdlet to get the contents of the Download.zip file and save it in the $b variable. Because the command omits the ReadCount parameter, it uses the default value of 1. - -The fourth command uses the Set-Content cmdlet to write the bytes in the $b variable to the Download.zip file on a file share. Because the content is a collection of objects, rather than a single object that contains a byte array, the command fails. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) - [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-Item-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-Item-for-FileSystem.md deleted file mode 100644 index d8d8217e74cf..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-Item-for-FileSystem.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Get-Item for FileSystem -online version: http://go.microsoft.com/fwlink/?LinkId=821468 ---- - -# Get-Item for FileSystem -Gets files and folders. - -## Syntax - -``` -Get-Item [-Stream ] [] - -``` - -## Description - In the file system, the [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet gets files and folders. - - Note: This custom cmdlet help file explains how the [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet works in a file system drive. For information about the [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) -Path $null" or see [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) at http://go.microsoft.com/fwlink/?LinkID=113319. - -## Parameters - -### -Stream - Gets the specified alternate NTFS file stream from the file. Enter the stream name. Wildcards are supported. To get all streams, use an asterisk (*). This parameter is not valid on folders. - - Stream is a dynamic parameter that the FileSystem provider adds to the [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet. This parameter works only in file system drives. - - This parameter is introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|No alternate file streams| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.String[ ]

You can pipe a path to the Get-Item cmdlet.| -|Outputs|System.IO.FileInfo, System.IO.DirectoryInfo, Microsoft.PowerShell.Commands.AlternateStreamData

In the file system, Get-Item returns files and folders. If you use the Stream parameter, it returns AlternateStreamData objects.| - -## Example 1 - -``` -C:\PS>Get-Item C:\Users\User01\Downloads\InternetFile.docx -Stream * - - FileName: C:\Users\User01\Downloads\InternetFile.docx - -Stream Length ------- ------ -:$DATA 45056 -Zone.Identifier 26 - -Description ------------ -This command gets all stream data from a file that was downloaded from the Internet. The Zone.Identifier stream identifies a file that originated on the Internet. The $DATA stream is the default. - -The Stream parameter is introduced in Windows PowerShell 3.0. - -``` - -## Example 2 - -``` -C:\PS>Get-Item C:\ps-test\* -Stream Zone.Identifier -ErrorAction SilentlyContinue - - FileName: C:\ps-test\Copy-Script.ps1 - -Stream Length ------- ------ -Zone.Identifier 26 - - FileName: C:\ps-test\Start-ActivityTracker.ps1 - -Stream Length ------- ------ -Zone.Identifier 26 - -Description ------------ -This command gets Zone.Identifier stream data from all files in the C:\ps-test directory. The command uses the Stream parameter to specify the alternate stream and he ErrorAction parameter with a value of SilentlyContinue to suppress non-terminating errors that are generated when a file has no alternate data streams. - -The Stream parameter is introduced in Windows PowerShell 3.0. - -``` - -## Example 3 - -``` -C:\PS>Get-Item . - -Directory: C:\ - -Mode LastWriteTime Length Name ----- ------------- ------ ---- -d---- 7/26/2006 10:01 AM ps-test - -Description ------------ -This command gets the current directory. The dot (.) represents the item at the current location (not its contents). - -``` - -## Example 4 - -``` -C:\PS>Get-Item * - -Directory: C:\ps-test - -Mode LastWriteTime Length Name ----- ------------- ------ ---- -d---- 7/26/2006 9:29 AM Logs -d---- 7/26/2006 9:26 AM Recs --a--- 7/26/2006 9:28 AM 80 date.csv --a--- 7/26/2006 10:01 AM 30 filenoext --a--- 7/26/2006 9:30 AM 11472 process.doc --a--- 7/14/2006 10:47 AM 30 test.txt - -Description ------------ -This command gets the current directory of the C: drive. The object that is retrieved represents only the directory, not its contents. - -``` - -## Example 5 - -``` -C:\PS>Get-Item C:\ - -Description ------------ -This command gets the items in the C: drive. The wildcard character (*) represents all the items in the container, not just the container. - -In PowerShell, use a single asterisk (*) to get contents, instead of the traditional "*.*". The format is interpreted literally, so "*.*" would not retrieve directories or file names without a dot. - -``` - -## Example 6 - -``` -C:\PS>(Get-Item C:\Windows).LastAccessTime - -Description ------------ -This command gets the LastAccessTime property of the C:\Windows directory. LastAccessTime is just one property of file system directories. To see all of the properties of a directory, type "(Get-Item ) | Get-Member". - -``` - -## Example 7 - -``` -C:\PS>Get-Item C:\Windows\*.* -Exclude w* - -Description ------------ -This command gets items in the Windows directory with names that include a dot (.), but do not begin with w*. This command works only when the path includes a wildcard character (*) to specify the contents of the item. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) - [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Remove-Item-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Remove-Item-for-FileSystem.md deleted file mode 100644 index f0df596b8b62..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Remove-Item-for-FileSystem.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Remove-Item for FileSystem -online version: http://go.microsoft.com/fwlink/?LinkId=834954 ---- - -# Remove-Item for FileSystem -Deletes files and folders. - -## Syntax - -``` -Remove-Item [-Stream ] [] - -``` - -## Description - In file system drives, the [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) cmdlet deletes files and folders. - - If you use the Stream dynamic parameter, it deletes the specified alternate data stream, but does not delete the file. - - Note: This custom cmdlet help file explains how the [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) cmdlet works in a file system drive. For information about the [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) -Path $null" or see [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) at http://go.microsoft.com/fwlink/?LinkID=113373. - -## Parameters - -### -Stream - Deletes the specified alternate data stream from a file, but does not delete the file. Enter the stream name. Wildcards are supported. This parameter is not valid on folders. - - Stream is a dynamic parameter that the FileSystem provider adds to the [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) cmdlet. This parameter works only in file system drives. - - You can use the [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) cmdlet to delete an alternate data stream. However, it is not the recommended way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. - - This parameter is introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|| -|Outputs|| - -## Example 1 - -``` -C:\PS>Get-Item C:\Test\Copy-Script.ps1 -Stream Zone.Identifier - - FileName: \\C:\Test\Copy-Script.ps1 - -Stream Length ------- ------ -Zone.Identifier 26 - -C:\PS>Remove-Item C:\Test\Copy-Script.ps1 -Stream Zone.Identifier - -C:\PS>Get-Item C:\Test\Copy-Script.ps1 -Stream Zone.Identifier - -get-item : Could not open alternate data stream 'Zone.Identifier' of file 'C:\Test\Copy-Script.ps1'. -At line:1 char:1 -+ get-item 'C:\Test\Copy-Script.ps1' -Stream Zone.Identifier -+ [!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()]~~ - + CategoryInfo : ObjectNotFound: (C:\Test\Copy-Script.ps1:String) [Get-Item], FileNotFoundE - xception - + FullyQualifiedErrorId : AlternateDataStreamNotFound,Microsoft.PowerShell.Commands.GetItemCommand - -C:\PS>Get-Item C:\Test\Copy-Script.ps1 - - Directory: C:\Test - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 8/4/2011 11:15 AM 9436 Copy-Script.ps1 - -Description ------------ -This example shows how to use the Stream dynamic parameter of the Remove-Item cmdlet to delete an alternate data stream. The stream parameter is introduced in Windows PowerShell 3.0. - -The first command uses the Stream dynamic parameter of the Get-Item cmdlet to get the Zone.Identifier stream of the Copy-Script.ps1 file. - -The second command uses the Stream dynamic parameter of the Remove-Item cmdlet to remove the Zone.Identifier stream of the file. - -The third command uses the Stream dynamic parameter of the Get-Item cmdlet to verify that the Zone.Identifier stream is deleted. - -The fourth command Get-Item cmdlet without the Stream parameter to verify that the file is not deleted. - -``` - -## Example 2 - -``` -C:\PS>Remove-Item C:\Test\*.* - -Description ------------ -This command deletes all of the files with names that include a dot (.) from the C:\Test directory. Because the command specifies a dot, the command does not delete directories or files with no file name extension. - -``` - -## Example 3 - -``` -C:\PS>Remove-Item * -Include *.doc -Exclude *1* - -Description ------------ -This command deletes from the current directory all files with a .doc file name extension and a name that does not include "1". It uses the wildcard character (*) to specify the contents of the current directory. It uses the Include and Exclude parameters to specify the files to delete. - -``` - -## Example 4 - -``` -C:\PS>Remove-Item -Path C:\Test\hidden-RO-file.txt -Force - -Description ------------ -This command deletes a file that is both hidden and read-only. It uses the Path parameter to specify the file. It uses the Force parameter to give permission to delete it. Without Force, you cannot delete read-only or hidden files. - -``` - -## Example 5 - -``` -C:\PS>Get-ChildItem * -Include *.csv -Recurse | Remove-Item - -Description ------------ -This command deletes all of the CSV files in the current directory and all subdirectories recursively. - -Because the Recurse parameter in this cmdlet is faulty, the command uses the Get-Childitem cmdlet to get the desired files, and it uses the pipeline operator to pass them to the Remove-Item cmdlet. - -In the Get-ChildItem command, the Path parameter has a value of *, which represents the contents of the current directory. It uses the Include parameter to specify the CSV file type, and it uses the Recurse parameter to make the retrieval recursive. - -If you try to specify the file type in the path, such as "-path *.csv", the cmdlet interprets the subject of the search to be a file that has no child items, and Recurse fails. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) - [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Set-Content-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Set-Content-for-FileSystem.md deleted file mode 100644 index 12ca073388e1..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Set-Content-for-FileSystem.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Set-Content for FileSystem -online version: http://go.microsoft.com/fwlink/?LinkId=834955 ---- - -# Set-Content for FileSystem -Replaces the contents of a file with contents that you specify. - -## Syntax - -``` -Set-Content [-Encoding { | | | | | | | | | | }] [-Force] [-Stream ] [-Confirm] [-WhatIf] [] - -``` - -## Description - In file system drives, the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet overwrites or replaces the content of one or more files with the content that you specify. This cmdlet is not valid on folders. - - Note: This custom cmdlet help file explains how the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet works in a file system drive. For information about the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) -Path $null" or see [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) at http://go.microsoft.com/fwlink/?LinkID=113392. - -## Parameters - -### -Encoding - Specifies the file encoding. The default is ASCII. - - Valid values are: - - -- ASCII: Uses the encoding for the ASCII (7-bit) character set. - - -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. - - -- Byte: Encodes a set of characters into a sequence of bytes. - - -- String: Uses the encoding type for a string. - - -- Unicode: Encodes in UTF-16 format using the little-endian byte order. - - -- UTF7: Encodes in UTF-7 format. - - -- UTF8: Encodes in UTF-8 format. - - -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. - - Encoding is a dynamic parameter that the FileSystem provider adds to the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet. This parameter works only in file system drives. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|ASCII| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Force - Replaces the contents of a file, even if the file is read-only. Without this parameter, read-only files are not changed. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Stream - Creates or replaces the content in the specified alternate data stream. If the stream does not yet exist, [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) creates it. Enter the stream name. Wildcards are not supported. - - Stream is a dynamic parameter that the FileSystem provider adds to the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet. This parameter works only in file system drives. - - You can use the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet to change the content of the Zone.Identifier alternate data stream. However, it is not the recommended way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. - - This parameter is introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.Object[], System.String[], System.Management.Automation.PSCredential

You can pipe a value (object), a path, or a credential object to Set-Content| -|Outputs|None or System.String

When you use the Passthru parameter, Set-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.| - -## Example 1 - -``` -C:\PS>Set-Content -Path C:\Test1\test*.txt -Value "Hello, World" - -Description ------------ -This command replaces the contents of all files in the Test1 directory that have names beginning with "test" with "Hello, World". This example shows how to specify content by typing it in the command. - -``` - -## Example 2 - -``` -C:\PS>Get-Date | Set-Content C:\Test1\date.csv - -Description ------------ -This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. The pipeline operator passes the result to Set-Content, which creates the file and writes the content. - -If the Test1 directory does not exist, the command fails, but if the file does not exist, the command will create it. - -``` - -## Example 3 - -``` -C:\PS>Get-Content Notice.txt | ForEach-Object {$_ -replace "Warning", "Caution"} | Set-Content Notice.txt - -Description ------------ -This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. - -It uses the Get-Content cmdlet to get the content of Notice.txt. The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. The expression uses the `$_` symbol to refer to the current item and the Replace parameter to specify the text to be replaced. - -Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content. - -The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. Without them, the command will fail because the two functions will be trying to access the same file. - -``` - -## Example 4 - -``` -C:\PS>Get-Content test.xml | Set-Content final.xml -Force -Encoding UTF8 - -Description ------------ -This command replaces the contents of the final.xml file with the contents of the test.xml file. - -The command uses the Force parameter so that the command is successful even if the Final.xml file is read-only. It uses the Encoding dynamic parameter to specify an encoding of UTF-8. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) - [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Test-Path-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Test-Path-for-FileSystem.md deleted file mode 100644 index 6bf537a57e86..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Test-Path-for-FileSystem.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Test-Path for FileSystem -online version: http://go.microsoft.com/fwlink/?LinkId=834958 ---- - -# Test-Path for FileSystem -Determines whether all elements of a file or directory path exist. - -## Syntax - -``` -Test-Path [-NewerThan ] [-OlderThan ] [] - -``` - -## Description - In a file system drive, [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) can tell whether a path is valid, whether all elements of the path exist, or report whether a path leads to a file or a directory. It can also tell whether a file was changed before or after a particular date. - - Note: This custom cmdlet help file explains how the [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) cmdlet works in a file system drive. For information about the [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) -Path $null" or see [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) at http://go.microsoft.com/fwlink/?LinkID=113418. - -## Parameters - -### -OlderThan - Returns "True" when the LastWriteTime value of a file is less than the specified date. Otherwise, it returns "False". Enter a DateTime object, such as one that the [Get-Date](../../../Microsoft.PowerShell.Utility/Get-Date.md) cmdlet returns, or a string that can be converted to a DateTime object, such as "August 10, 2011 2:00 PM". - - OlderThan is a dynamic parameter that works only on file system paths. It was introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -NewerThan - Returns "True" when the LastWriteTime value of a file is greater than the specified date. Otherwise, it returns "False". Enter a DateTime object, such as one that the [Get-Date](../../../Microsoft.PowerShell.Utility/Get-Date.md) cmdlet returns, or a string that can be converted to a DateTime object, such as "August 10, 2011 2:00 PM". - - NewerThan is a dynamic parameter that works only on file system paths. It was introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.String

You can pipe a string that contains a path (but not a literal path) to Test-Path.| -|Outputs|System.Boolean| - -## Example 1 - -``` -C:\PS>Test-Path -Path "C:\Documents and Settings\NicoleH" - -Description ------------ -This command tells whether all elements in the path exist, that is, the C: directory, the Documents and Settings directory, and the NicoleH directory. If any are missing, the cmdlet returns FALSE. Otherwise, it returns TRUE. - -``` - -## Example 2 - -``` -C:\PS>Test-Path -Path $profile - -C:\PS>Test-Path -Path $profile -IsValid - -Description ------------ -These commands test the path to the PowerShell profile. - -The first command determines whether all elements in the path exist. The second command determines whether the syntax of the path is correct. In this case, the path is FALSE, but the syntax is correct (TRUE). These commands use $profile, the automatic variable that points to the location for the profile, even if the profile does not exist. - -For more information about automatic variables, see about_Automatic_Variables. - -``` - -## Example 3 - -``` -C:\PS>Test-Path -Path "C:\CAD\Commercial Buildings\*" -Exclude *.dwg - -Description ------------ -This command tells whether there are any files in the Commercial Buildings directory other than .dwg files. - -The command uses the Path parameter to specify the path. Because it includes a space, the path is enclosed in quotes. The asterisk at the end of the path indicates the contents of the Commercial Building directory. (With long paths, like this one, type the first few letters of the path, and then use the TAB key to complete the path.) - -The command uses the Exclude parameter to specify files that will be omitted from the evaluation. - -In this case, because the directory contains only .dwg files, the result is FALSE. - -``` - -## Example 4 - -``` -C:\PS>Test-Path -Path $profile -PathType Leaf - -Description ------------ -This command tells whether the path stored in the $profile variable leads to a file. In this case, because the PowerShell profile is a .ps1 file, the cmdlet returns TRUE. - -``` - -## Example 5 - -``` -C:\PS>Test-Path -Path HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell - -TRUE - -C:\PS> Test-Path -Path HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy -FALSE - -Description ------------ -These commands use the Test-Path cmdlet with the PowerShell registry provider. - -The first command tests whether the registry path to the Microsoft.PowerShell registry key is correct on the system. If PowerShell is installed correctly, the cmdlet returns TRUE. - -Test-Path does not work correctly with all PowerShell providers. For example, you can use Test-Path to test the path to a registry key, but if you use it to test the path to a registry entry, it always returns FALSE, even if the registry entry is present. - -``` - -## Example 6 - -``` -C:\PS>Test-Path $pshome\PowerShell.exe -NewerThan "July 13, 2009" - -Description ------------ -This command uses the NewerThan dynamic parameter to determine whether the PowerShell.exe file on the computer is newer than July 13, 2009. - -The NewerThan parameter works only in file system drives. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) - [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/Function-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/Function-Provider.md deleted file mode 100644 index 41f3e7b0068e..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/Function-Provider.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Function Provider -online version: http://go.microsoft.com/fwlink/?LinkId=834961 ---- - - -# *Function* provider - - -## Provider name - - Function - - -## Drives - - `Function:` - - -## Short description - - Provides access to the functions defined in PowerShell. - - -## Detailed description - - The PowerShell **Function** provider lets you get, add, change, clear, and delete the functions and filters in PowerShell. - - A function is a named block of code that performs an action. When you type the function name, the code in the function runs. A filter is a named block of code that establishes conditions for an action. You can type the name of the filter in place of the condition, such as in a [Where-Object](../Where-Object.md) command. - - In the `Function:` drive, functions are preceded by the label "Function" and filters are preceded by the label "Filter", but they operate properly when used in the correct context regardless of the label. - - The **Function** provider is a flat namespace that contains only the function and filter objects. Neither functions nor filters have child items. - - Each function is an instance of the [System.Management.Automation.FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) class. Each filter is an instance of the [System.Management.Automation.FilterInfo](https://msdn.microsoft.com/library/system.management.automation.filterinfo) class. - - The examples in this section show how to manage functions, but the same methods can be used with filters. - - The **Function** provider exposes its data store in the `Function:` drive. To work with functions, you can change your location to the `Function:` drive (`set-location Function:`). Or, you can work from another PowerShell drive. To reference a function from another location, use the drive name (`Function:`) in the path. - - The **Function** provider supports all of the cmdlets whose names contain the *Item* noun (the `*-Item` cmdlets), except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). And, it supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets whose names contain the *ItemProperty* noun (the `*-ItemProperty` cmdlets), and it does not support the `-Filter` parameter in any cmdlet. - - -## Capabilities - - ShouldProcess - - -## Examples - - -### Getting to the `Function:` drive - - -#### Example 1 - - Changes the current location to the `Function:` drive. You can use this command from any drive in PowerShell. To return to a file system drive, type the drive name. For example, type `set-location c:`. - -```powershell -Set-Location Function: -``` - - -### Getting functions - - -#### Example 1 - - This command gets the list of all the functions in the current session. You can use this command from any PowerShell drive. - -```powershell -Get-ChildItem -Path Function: -``` - - -#### Example 2 - - This command gets the `man` function from the `Function:` drive. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get the function. The pipeline operator (`|`) sends the result to [Format-Table](../../Microsoft.PowerShell.Utility/Format-Table.md). - - The `-Wrap` parameter directs text that does not fit on the line onto the next line. The `-Autosize` parameter resizes the table columns to accommodate the text. - -```powershell -Get-Item -Path man | Format-Table -Wrap -Autosize -``` - - If you are in a different drive, add the drive name (`Function:`) to the path. - - -#### Example 3 - - These commands both get the function named `c:`. The first command can be used in any drive. The second command is used in the `Function:` drive. - - Because the name ends in a colon, which is the syntax for a drive, you must qualify the path with the drive name. Within the `Function:` drive, you can use either format. In the second command, the dot (`.`) represents the current location. - -``` -c:\PS> Get-Item -Path Function:c: -PS Function> Get-Item -Path .\c: -``` - - -### Creating a function - - -#### Example 1 - - This command uses the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create a function called `HKLM:`. The expression in braces is the script block that is represented by the function name. - -```powershell -New-Item -Path Function:HKLM: -Value {Set-Location HKLM:} -``` - - You can also create a function by typing it at the PowerShell command line. For example, tpe `Function:HKLM: {set-location HKLM:}`. If you are in the `Function:` drive, you can omit the drive name. -Because you cannot specify the "Filter" label in [New-Item](../../Microsoft.PowerShell.Management/New-Item.md), filters are labeled as functions, but they operate properly with any label. To create a filter with the "Filter" label, type the filter at the command line. For example, type `filter:Running {$_.Status -eq "Running"}`. - - -#### Example 2 - - This command uses the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create a function called `Csrss`. It uses the `-Options` dynamic parameter to specify a value of `ReadOnly` for the **Options** property of the function. - -```powershell -New-Item -Path Function: -Name csrss -Options readonly -Value {Get-Process csrss} -``` - - This command works from any location. If you are in the `Function:` drive, you can use a dot (`.`) to specify the path. The dot represents the current location. - - -### Deleting a function - - -#### Example 1 - - This command deletes the `HKLM:` function from the current session. - -```powershell -Remove-Item Function:HKLM: -``` - - -#### Example 2 - - This command deletes all the functions from the current session except for the functions whose **Options** property has a value of `Constant`. Without the `-Force` parameter, the command does not delete functions whose **Options** property has a value of `ReadOnly`. - -```powershell -Remove-Item Function:* -Force -``` - - When you delete all the functions, the command prompt changes because the prompt function, which defines the content of the command prompt, is deleted. - - -### Displaying the properties and methods of functions - - -#### Example 1 - - This command uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get all the functions. The pipeline operator sends the results to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet, which displays the methods and the properties of the object. - -```powershell -Get-Item -Path Function:* | Get-Member -``` - - When you pipe a collection of objects (such as the collection of functions in the `Function:` drive) to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately and returns information about each object type that it finds. If all of the objects are of the same type, it returns information about the single object type. In this case, all of the functions are [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) objects. -To get information about the collection of [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) objects, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, type `Get-Member -InputObject (Get-Item Function:*)`. When you use the `-InputObject` parameter, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. - - -#### Example 2 - - This command lists the values of the properties of the `prompt` function. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `prompt` function. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. The [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command uses the `-Property` parameter with a wildcard character (`*`) to format and to display the values of all of the properties of the `prompt` function. - -```powershell -Get-Item Function:prompt | Format-List -Property * -``` - - -### Changing the properties of a function - - -#### Example 1 - - You can use the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet with the `-Options` dynamic parameter to change the value of the **Options** property of a function. - - This command sets the `AllScope` and `ReadOnly` options for the `prompt` function. This command uses the `-Options` dynamic parameter of the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet. The `-Options` parameter is available in [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) only when you use it with the **Alias** or **Function** provider. - -```powershell -Set-Item -Path Function:prompt -Options "AllScope,ReadOnly" -``` - - -#### Example 2 - - This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the `prompt` function so that it displays the time before the path. - -```powershell -Set-Item -Path Function:prompt -Value {'PS '+ $(Get-Date -Format t) + " " + $(Get-Location) + '> '} -``` - - The change affects both the **Definition** and **ScriptBlock** properties of the [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) object. To see the effect of the change, type `Get-Item -Path Function:prompt | Format-List -Property *`. - - -#### Example 3 - - This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `help` function to `gh`. - -```powershell -Rename-Item -Path Function:help -NewName gh -``` - - -### Copying a function - - -#### Example 1 - - This command copies the `prompt` function to `oldPrompt`, effectively creating a new name for the script block that is associated with the prompt function. You can use this to save the original prompt function if you plan to change it. - - The **Options** property of the new function has a value of `None`. To change the value of the **Options** property, use [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md). - -```powershell -Copy-Item -Path Function:prompt -Destination Function:oldPrompt -``` - - -## 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. - - -### `Options` <[System.Management.Automation.ScopedItemOptions](https://msdn.microsoft.com/library/system.management.automation.scopeditemoptions)> - - Determines the value of the **Options** property of a function. - -|Value|Description| -|-----------|-----------------| -|`None`|No options. `None` is the default.| -|`Constant`|The function cannot be deleted, and its properties cannot be changed. `Constant` is available only when you are creating a function. You cannot change the option of an existing function to `Constant`.| -|`Private`|The function is visible only in the current scope (not in child scopes).| -|`ReadOnly`|The properties of the function cannot be changed except by using the `-Force` parameter. You can use [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) to delete the function.| -|`AllScope`|The function is copied to any new scopes that are created.| - - -#### Cmdlets supported: - - -- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - - -## See also - - [about_Functions](../About/about_Functions.md) - [about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/Registry-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/Registry-Provider.md deleted file mode 100644 index 0504ad3f83cd..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/Registry-Provider.md +++ /dev/null @@ -1,287 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Registry Provider -online version: http://go.microsoft.com/fwlink/?LinkId=821468 ---- - - -# *Registry* provider - - -## Provider name - - **Registry** - - -## Drives - - `HKLM:`, `HKCU:` - - -## 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. - - Registry keys are represented as instances of the [Microsoft.Win32.RegistryKey](https://docs.microsoft.com/en-us/dotnet/api/microsoft.win32.registrykey) class. Registry entries are represented as instances of the [PSCustomObject](https://msdn.microsoft.com/library/system.management.automation.pscustomobject) class. - - The **Registry** provider lets you access a hierarchical namespace that consists of registry keys and subkeys. Registry entries and values are not components of that hierarchy. Instead, they are properties of each of the keys. - - The **Registry** provider supports all the cmdlets that contain the *Item* noun (the `*-Item` cmdlets), such as [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md), and [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md), except for the [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) cmdlet. Use the `*-Item` cmdlets when you work with registry keys and subkeys. - - The **Registry** provider also supports the cmdlets that contain the *ItemProperty* noun (the `*-ItemProperty` cmdlets). Use the `*-ItemProperty` cmdlets when you work with registry entries. You cannot use the cmdlets that contain the *Content* noun (the `*-Content` cmdlets) with the **Registry** provider. - - Each registry key is protected by a security descriptor. You can use [Get-Acl](../../Microsoft.PowerShell.Security/Get-Acl.md) to view the security descriptor of a key. - - -## Capabilities - - **ShouldProcess**, **UseTransactions** - - -## Examples - - -### Navigating the registry - - -#### Example 1 - - This command sets the current location to the `HKEY_LOCAL_MACHINE\Software` registry key: - -```powershell -Set-Location HKLM:\software -``` - - -#### Example 2 - - This command gets an object that represents the current location: - -```powershell -Get-Location -``` - - -### Managing registry keys - - -#### Example 1 - - This command gets each immediate subkeys of the `HKEY_LOCAL_MACHINE\Software` registry key: - -```powershell -Get-ChildItem -Path HKLM:\software -``` - - -#### Example 2 - - This command creates the `TestNew` subkey under the `HKCU:\Environment` subkey: - -```powershell -New-Item -Path hkcu:\Environment\TestNew -``` - - -#### Example 3 - - This command deletes the `TestNew` subkey of the `HKEY_CURRENT_USER\Environment` key: - -```powershell -Remove-Item -Path hkcu:\Environment\TestNew -``` - - -#### Example 4 - - This command copies the `TestNew` key to the `TestCopy` subkey: - -```powershell -Copy-Item -Path hkcu:\Environment\TestNew hkcu:\Environment\TestNew\TestCopy -``` - - -#### Example 5 - - This command gets all the subkeys of the `HKEY_LOCAL_MACHINE\Software` registry key: - -```powershell -Get-ChildItem -Path HKLM:\Software -Recurse -``` - - -#### Example 6 - - This command moves the `HKEY_CURRENT_USER\Environment\testnewcopy` registry key, its subkeys and their registry entries to the `HKEY_CURRENT_USER\Environment\testnew` key: - -```powershell -Move-Item -Path hkcu:\environment\testnewcopy -Destination hkcu:\environment\testnew -``` - - -#### Example 7 - - This command renames the `HKEY_CURRENT_USER\Environment\testnew` registry key to `HKEY_CURRENT_USER\Environment\test`: - -```powershell -Rename-Item -Path hkcu:\environment\testnew\ -NewName test -``` - - -#### Example 8 - - This command gets the security descriptor of the specified registry key: - -```powershell -Get-Acl -Path hkcu:\environment\testnew | Format-List -Property * -``` - - -### Managing registry entries - - -#### Example 1 - - This command gets the registry entries in the `HKEY_CURRENT_USER\Environment` registry key: - -```powershell -Get-ItemProperty -Path hkcu:\Environment -``` - - This command gets the **Default** registry entry only when it contains data. - - -#### Example 2 - - This command gets the **Temp** registry entry in the `HKEY_CURRENT_USER\Environment` key: - -```powershell -Get-ItemProperty -Path hkcu:\Environment -Name Temp -``` - - -#### Example 3 - - This command creates a **PSTest** registry entry in the `HKEY_CURRENT_USER\Environment` key and sets its value to 1: - -```powershell -New-ItemProperty -Path hkcu:\environment -Name PSTest -Value 1 -PropertyType dword -``` - - -#### Example 4 - - This command changes the value of the **PSTest** registry entry in the `HKEY_CURRENT_USER\Environment` key to "Start" and changes its data type to REG_SZ (string): - -```powershell -Set-ItemProperty -Path hkcu:\environment -Name PSTest -Value Start -Type string -``` - - -#### Example 5 - - This command renames the **PSTest** registry entry in the `HKEY_CURRENT_USER\Environment` key to **PSTestNew**: - -```powershell -Rename-ItemProperty -Path hkcu:\environment -Name PSTest -NewName PSTestNew -``` - - -#### Example 6 - - This command copies the **PSTestNew** registry entry from the `HKEY_CURRENT_USER\Environment` key to the `HKEY_CURRENT_USER\Environment\testnewcopy` key: - -```powershell -Copy-ItemProperty -Path hkcu:\environment -Destination hkcu:\environment\testnewcopy -Name pstestnew -``` - - -#### Example 7 - - The command moves the **pstestnew** registry entry from the `HKEY_CURRENT_USER\environment\testnewcopy` key to the `HKEY_CURRENT_USER\environment\testnew` key: - -```powershell -Move-ItemProperty -Path hkcu:\environment\testnewcopy -Destination hkcu:\environment\testnew -Name pstestnew -``` - - -#### Example 8 - - This command clears the value of the **pstestnew** registry entry in the `HKEY_CURRENT_USER\Environment\testnew` key: - -```powershell -Clear-ItemProperty -Path hkcu:\environment\testnew -Name pstestnew -``` - - You can use the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) cmdlet to clear the value of the default registry entry for a subkey. For example, the following command clears the value of the default entry of the `HKEY_CURRENT_USER\Environment\testnew` registry key: - -```powershell -Clear-Item -Path hkcu:\environment\testnew -``` - - -#### Example 9 - - This command deletes the pstestnew registry entry from the `HKEY_CURRENT_USER\Environment\testnew` registry key: - -```powershell -Remove-ItemProperty -Path hkcu:\environment\testnew -Name pstestnew -``` - - -#### Example 10 - - This command changes the value of the default registry entry in the `HKEY_CURRENT_USER\Environment\testnew` key to "default value": - -```powershell -Set-ItemProperty -Path hkcu:\environment\testnew -Name "(default)" -Value "default value" -``` - - You can also change the default value of a registry key by using the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet. For example, the following command updates the default value of the testnew key: - -```powershell -Set-Item -Path hkcu:\environment\testnew -Value "another default value" -``` - - -## 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](https://msdn.microsoft.com/library/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](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) cmdlet. It is also available on the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) 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](../../Microsoft.PowerShell.Management/Set-Item.md) - -- [Set-ItemProperty](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) - - -## See also - - [about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/Variable-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/Variable-Provider.md deleted file mode 100644 index aed6607db0b1..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/Providers/Variable-Provider.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Variable Provider -online version: http://go.microsoft.com/fwlink/?LinkId=834963 ---- - - -# *Variable* provider - - -## Provider name - - Variable - - -## Drives - - `Variable:` - - -## Short description - - Provides access to the PowerShell variables and to their values. - - -## Detailed description - - The PowerShell **Variable** provider lets you get, add, change, clear, and delete PowerShell variables in the current console. - - The PowerShell **Variable** provider supports the variables that PowerShell creates, including the automatic variables, the preference variables, and the variables that you create. - - The **Variable** provider is a flat namespace that contains only the variable objects. The variables have no child items. - - Most of the variables are instances of the [System.Management.Automation.PSVariable](https://msdn.microsoft.com/library/system.management.automation.psvariable) class. However, there are some variations. For example, the `?` variable is a member of the `QuestionMarkVariable` internal class, and the `MaximumVariableCount` variable is a member of the `SessionStateCapacityVariable` internal class. - - The **Variable** provider exposes its data store in the `Variable:` drive. To work with variables, you can change your location to the `Variable:` drive (`set-location Variable:`), or you can work from any other PowerShell drive. To reference a variable from another location, use the drive name (`Variable:`) in the path. - - PowerShell includes a set of cmdlets designed especially to view and to change variables: - - - [Get-Variable](../../Microsoft.PowerShell.Utility/Get-Variable.md) - - [New-Variable](../../Microsoft.PowerShell.Utility/New-Variable.md) - - [Set-Variable](../../Microsoft.PowerShell.Utility/Set-Variable.md) - - [Remove-Variable](../../Microsoft.PowerShell.Utility/Remove-Variable.md) - - [Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) - - When you use these cmdlets, you do not need to specify the `Variable:` drive in the name. - - The **Variable** provider supports all of the cmdlets whose names contain the *Item* noun (the `*-Item` cmdlets), except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). The **Variable** provider supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets whose names contain the *ItemProperty* noun (the `*-ItemProperty` cmdlets), and it does not support the `-Filter` parameter in any cmdlet. - - You can also use the PowerShell expression parser to create, view, and change the values of variables without using the cmdlets. When working with variables directly, use a dollar sign (`$`) to identify the name as a variable and the assignment operator (`=`) to establish and change its value. For example, `$p = Get-Process` creates the `p` variable and stores the results of a `Get-Process` command in it. - - -## Capabilities - - ShouldProcess - - -## Examples - - -### Getting to the `Variable:` drive - - -#### Example 1 - - This command changes the current location to the `Variable:` drive. You can use this command from any drive in PowerShell. To return to a file system drive, type the drive name. For example, type `set-location c:`. - -```powershell -Set-Location Variable: -``` - - -### Displaying the value of variables - - -#### Example 1 - - This command gets the list of all the variables and their values in the current session. You can use this command from any PowerShell drive. - -```powershell -Get-ChildItem -Path Variable: -``` - - -#### Example 2 - - This command gets the variables with names that begin with "max". You can use this command from any PowerShell drive. - -```powershell -Get-ChildItem -Path Variable:max* -``` - - If you are in the `Variable:` drive, you can omit the drive name from the path. - - -#### Example 3 - - This command gets the value of the `WhatIfPreference` variable by typing it at the command line. - - The name of the variable is preceded by a dollar sign (`$`) to indicate that it is a variable. The `Variable:` drive name is not specified. - -```powershell -$WhatIfPreference -``` - - -#### Example 4 - - This command uses the `-LiteralPath` parameter of [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) to get the value of the `?` variable from within the `Variable:` drive. [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) does not attempt to resolve any wildcards in the values of the `-LiteralPath` parameter. - -```powershell -Get-ChildItem -Literalpath ? -``` - - To display the value of a variable with a special character name without a cmdlet, type a dollar sign (`$`) and the variable name. For example, to display the value of the `?` variable, type `$?`. - - -#### Example 5 - - This command gets the variables that have the values of `ReadOnly` or `Constant` for their **Options** property. - -```powershell -Get-ChildItem -Path Variable: | Where-Object {$_.options -Match "Constant" -or $_.options -Match "ReadOnly"} | Format-List -Property name, value, options -``` - - -### Creating a new variable - - -#### Example 1 - - This command creates the `services` variable and stores the results of a [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command in it. Because the current location is in the `Variable:` drive, the value of the `-Path` parameter is a dot (`.`), which represents the current location. - - The parentheses around the [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command ensure that the command is executed before the variable is created. Without the parentheses, the value of the new variable is a "Get-Service" string. - -```powershell -New-Item -Path . -Name services -Value (Get-Service) -``` - - If you are not in the `Variable:` drive, include the `Variable:` drive name in the path. - - -#### Example 2 - - This command creates a `services` variable and stores the result of a [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command in it. - - The command uses a dollar sign (`$`) to indicate a variable and the assignment operator (`=`) to assign the result of the [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command to the newly created variable. - -```powershell -$services = Get-Service -``` - - To create a variable without a value, omit the assignment operator. - - -### Displaying the properties and methods of variables - - -#### Example 1 - - This command uses the Get-Item cmdlet to get all variables. The pipeline operator (`|`) sends the results to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet, which displays the methods and properties of the object. - -```powershell -Get-Item -Path Variable:* | Get-Member -``` - - When you pipe a collection of objects (such as the collection of variables in the `Variable:` drive) to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately and returns information about each of the object types that it finds. -To get information about the collection of objects in the `Variable:` drive, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, `Get-Member -InputObject (Get-Item Variable:*)`. When you use `-InputObject`, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. - - -#### Example 2 - - This command lists the values of the properties of the `home` variable. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `home` variable. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. The [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command uses the `-Property` parameter with a wildcard character (`*`) to format and to display the values of all of the properties of the `home` variable. - -```powershell -Get-Item Variable:home | Format-List -Property * -``` - - -### Changing the properties of a variable - - -#### Example 1 - - This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `a` variable to `processes`. - -```powershell -Rename-Item -Path Variable:a -NewName processes -``` - - -#### Example 2 - - This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the value of the `ErrorActionPreference` variable to "Stop". - -```powershell -Set-Item -Path Variable:ErrorActionPreference -Value Stop -``` - - -#### Example 3 - - This command changes the value of the `ErrorActionPreference` variable to "Stop". - - It uses a dollar sign (`$`) to indicate a variable and the assignment operator (`=`) to assign the value. - -```powershell -$ErrorActionPreference = Stop -``` - - -### Copying a variable - - -#### Example 1 - - This command uses the [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) cmdlet to copy the `processes` variable to `old_processes`. This creates a new variable named `old_processes` that has the same value as the `processes` variable. - -```powershell -Copy-Item -Path Variable:processes -Destination Variable:old_processes -``` - - If the command is issued from within the `Variable:` drive, you can omit the drive name from the value of the `-Path` parameter. - - -#### Example 2 - - This command copies the `processes` variable to `old_processes` without using a cmdlet. It uses the dollar sign (`$`) to indicate variables and the assignment operator to assign the value of `$processes` to `old_processes`. - -```powershell -$old_processes = $processes -``` - - -### Deleting a variable - - -#### Example 1 - - This command deletes the `serv` variable from the current session. You can use this command in any PowerShell drive. - -```powershell -Remove-Variable -Path Variable:serv -``` - - -#### Example 2 - - This command deletes all variables from the current session except for the variables whose **Options** property has a value of `Constant`. Without the `-Force` parameter, the command does not delete variables whose **Options** property has a value of `ReadOnly`. - -```powershell -Remove-Item Variable:* -Force -``` - - -### Setting the value of a variable to NULL - - -#### Example 1 - - This command uses the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) cmdlet to change the value of the `processes` variable to NULL. - -```powershell -Clear-Item -Path Variable:processes -``` - - -#### Example 2 - - This command clears the value of the `processes` variable by assigning a null value to it. It uses the `$null` automatic variable to represent the NULL value. - -```powershell -$processes = $null -``` - - -## See also - - [about_Variables](../About/about_Variables.md) - [about_Automatic_Variables](../About/about_Automatic_Variables.md) - [about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/about_Alias_Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/about_Alias_Provider.md new file mode 100644 index 000000000000..dd356953e104 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/Providers/about_Alias_Provider.md @@ -0,0 +1,321 @@ +--- +ms.date: 10/18/2018 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: Alias Provider +online version: http://go.microsoft.com/fwlink/?LinkId=834943 +--- +# Alias provider + +## Provider name + +Alias + +## Drives + +`Alias:` + +## Capabilities + +**ShouldProcess** + +## Short description + +Provides access to the PowerShell aliases and the values that they represent. + +## Detailed description + +The PowerShell **Alias** provider lets you get, add, change, clear, and delete +aliases in PowerShell. + +An alias is an alternate name for a cmdlet, function, executable file, +including scripts. PowerShell includes a set of built-in aliases. You can add +your own aliases to the current session and to your PowerShell profile. + +The **Alias** drive is a flat namespace that contains only the alias objects. +The aliases have no child items. + +The **Alias** provider supports the following cmdlets, which are covered +in this article. + +- [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) +- [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) + +{{Make sure list is correct}} + +PowerShell includes a set of cmdlets that are designed to view and to change aliases. When you use **Alias** cmdlets, you do not need to specify the `Alias:` drive in the name. This article does not cover working with +**Alias** cmdlets. + +- [Export-Alias](../../Microsoft.PowerShell.Utility/Export-Alias.md) +- [Get-Alias](../../Microsoft.PowerShell.Utility/Get-Alias.md) +- [Import-Alias](../../Microsoft.PowerShell.Utility/Import-Alias.md) +- [New-Alias](../../Microsoft.PowerShell.Utility/New-Alias.md) +- [Set-Alias](../../Microsoft.PowerShell.Utility/Set-Alias.md) + +## Types exposed by this provider + +Each alias is an instance of the +[System.Management.Automation.AliasInfo](/dotnet/api/system.management.automation.aliasinfo) class. + +## Navigating the Alias drive + +The **Alias** provider exposes its data store in the `Alias:` drive. To work +with aliases, you can change your location to the `Alias:` drive by using the +following command: + +```powershell +Set-Location Alias: +``` + +To return to a file system drive, type the drive name. For example, type: + +```powershell +Set-Location C: +``` + +You can also work with the Alias provider from any other PowerShell drive. To +reference an alias from another location, use the `Alias:` drive name in the +path. + +> [!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](../../Microsoft.PowerShell.Management/Get-ChildItem.md), +> `cd` is an alias for [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md). and `pwd` is +> an alias for [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md). + +### Displaying the Contents of the Alias: drive + +This command gets the list of all the aliases when the current location is the +`Alias:` drive. It uses a wildcard character `*` to indicate all the contents +of the current location. + +```powershell +PS Alias:\> Get-Item -Path * +``` + +In the `Alias:` drive, a dot `.`, which represents the current location, and a +wildcard character `*`, which represents all items in the current location, +have the same effect. For example, `Get-Item -Path .` or `Get-Item \*` produce +the same result. + +The Alias provider has no containers, so the above command has the +same effect when used with `Get-ChildItem`. + +```powershell +Get-ChildItem -Path Alias: +``` + +### Get a selected alias + +This command gets the `ls` alias. +Because it includes the path, you can use it in any PowerShell drive. + +```powershell +Get-Item -Path Alias:ls +``` + +If you are in the `Alias:` drive, you can omit the drive name from the path. + +### Get all aliases for a specific cmdlet + +This command gets a list of the aliases that are associated with the +`Get-ChildItem` cmdlet. It uses the **Definition** property, which stores +the cmdlet name. + +```powershell +Get-Item -Path Alias:* | Where-Object {$_.Definition -eq "Get-ChildItem"} +``` + +## Creating aliases + +### Create an alias from the Alias: drive + +This command creates the `serv` alias for the `Get-Service` cmdlet. Because the +current location is in the `Alias:` drive, the `-Path` parameter is not +needed. + +This command also uses the `-Options` dynamic parameter to set the **AllScope** +option on the alias. The `-Options` parameter is available in +the `New-Item` cmdlet only when you are in the `Alias:` drive. The dot (`.`) +indicates the current directory, which is the alias drive. + +```powershell +PS Alias:\> New-Item -Path . ` + -Name serv ` + -Value Get-Service ` + -Options "AllScope" +``` + +### Create an alias with an absolute path + +You can create an alias for any item that invokes a command. +This command creates the `np` alias for `Notepad.exe`. + +```powershell +New-Item -Path Alias:np -Value c:\windows\notepad.exe +``` + +### Create an alias to a new function + +You can create an alias for any function. You can use this feature to create an +alias that includes both a cmdlet and its parameters. + +The first command creates the `CD32` function, which changes the current +directory to the `System32` directory. The second command creates the `go` +alias for the `CD32` function. + +When the command is complete, you can use either `CD32` or `go` to invoke the +function. + +```powershell +function CD32 {Set-Location -Path c:\windows\system32} +Set-Item -Path Alias:go -Value CD32 +``` + +## Changing aliases + +### Change the options of an alias + +You can use the `Set-Item` cmdlet with the `-Options` dynamic parameter to +change the value of the `-Options` property of an alias. + +This command sets the **AllScope** and **ReadOnly** options for the `dir` +alias. The command uses the `-Options` dynamic parameter of the `Set-Item` +cmdlet. The `-Options` parameter is available in `Set-Item` when you use it +with the **Alias** or **Function** provider. + +```powershell +Set-Item -Path Alias:dir -Options "AllScope,ReadOnly" +``` + +### Change an aliases referenced command + +This command uses the `Set-Item` cmdlet to change the `gp` alias so that it +represents the `Get-Process` cmdlet instead of the `Get-ItemProperty` cmdlet. +The `-Force` parameter is required because the value of the **Options** +property of the `gp` alias is set to `ReadOnly`. Because the command is +submitted from within the `Alias:` drive, the drive is not specified in the +path. + +```powershell +Set-Item -Path gp -Value Get-Process -Force +``` + +The change affects the four properties that define the association between the +alias and the command. To view the effect of the change, type the following +command: + +```powershell +Get-Item -Path gp | Format-List -Property * +``` + +### Rename an alias + +This command uses the `Rename-Item` cmdlet to change the `popd` alias to `pop`. + +```powershell +Rename-Item -Path Alias:popd -NewName pop +``` + +## Copying an alias + +This command copies the `pushd` alias so that a new `push` alias is created for +the `Push-Location` cmdlet. + +When the new alias is created, its **Description** property has a null value. +And, its **Option** property has a value of `None`. If the command is issued +from within the `Alias:` drive, you can omit the drive name from the value of +the `-Path` parameter. + +```powershell +Copy-Item -Path Alias:pushd -Destination Alias:push +``` + +## Deleting an alias + +This command deletes the `serv` alias from the current session. +You can use this command in any PowerShell drive. + +```powershell +Remove-Item -Path Alias:serv +``` + +This command deletes aliases that begin with "s". +It does not delete read-only aliases. + +```powershell +Clear-Item -Path Alias:s* +``` + +### Delete read-only aliases + +This command deletes all aliases from the current session, except those with a +value of `Constant` for their **Options** property. The `-Force` +parameter allows the command to delete aliases whose **Options** property has a +value of `ReadOnly`. + +```powershell +Remove-Item Alias:* -Force +``` + +## 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. + +## 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. + +### Options [System.Management.Automation.ScopedItemOptions] + +Determines the value of the **Options** property of an alias. + +- `None`: No options. This value is the default. +- `Constant`:The alias cannot be deleted and its properties cannot be changed. + `Constant` is available only when you create an alias. You cannot change the option of an existing alias to `Constant`. +- `Private`:The alias is visible only in the current scope, not in the child + scopes. +- `ReadOnly`:The properties of the alias cannot be changed except by using the + `-Force` parameter. You can use `Remove-Item` to delete the alias. +- `AllScope`:The alias is copied to any new scopes that are created. + +#### Cmdlets supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) + +## 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](../Get-Help.md) command in a file system drive or use the `-Path` +parameter of [Get-Help](../Get-Help.md) to specify a file system drive. + +```powershell +Get-Help Get-ChildItem +``` + +```powershell +Get-Help Get-ChildItem -Path c: +``` + +{{Make provider specific>}} + +## See also + +[about_Aliases](../About/about_Aliases.md) + +[about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/about_Environment_Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/about_Environment_Provider.md new file mode 100644 index 000000000000..ca476ab2dbe4 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/Providers/about_Environment_Provider.md @@ -0,0 +1,219 @@ +--- +ms.date: 10/18/2018 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: Environment Provider +online version: https://go.microsoft.com/fwlink/?linkid=834944 +--- +# Environment provider + +## Provider name + +Environment + +## Drives + +`Env:` + +## Capabilities + +**ShouldProcess** + +## Short description + +Provides access to the Windows environment variables. + +## Detailed description + +The PowerShell **Environment** provider lets you get, add, change, clear, and delete environment +variables and values in PowerShell. + +**Environment** variables are dynamically named variables that describe the environment in which your programs run. Windows and PowerShell use environment variables to store persistent information that affect system +and process execution. Unlike PowerShell variables, environment variables are not subject to scope constraints. + +The **Environment** drive is a flat namespace containing the environment variables specific to the current user's session. The environment variables +have no child items. + +The **Envrionment** provider supports the following cmdlets, which are covered +in this article. + +- [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) +- [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) + +{{Make sure list is correct}} + +## Types exposed by this provider + +Each environment variable is an instance of the +[System.Collections.DictionaryEntry](/dotnet/api/system.collections.dictionaryentry) +class. The name of the variable is the dictionary key. The value of the +environment variable is the dictionary value. + +## Navigating the Environment drive + +The **Environment** provider exposes its data store in the `Env:` drive. To +work with environment variables, change your location to the `Env:` drive +(`Set-Location Env:`), or work from another PowerShell drive. To reference an +environment variable from another location, use the `Env:` drive name in the +path. + +```powershell +Set-Location Env: +``` + +To return to a file system drive, type the drive name. For example, type: + +```powershell +Set-Location C: +``` + +You can also work with the **Environment** provider from any other PowerShell +drive. To reference an environment variable from another location, use the drive name `Env:` in the path. + +The **Environment** provider also exposes environment variables using a variable +prefix of `$env:`. The following command views the contents of the +**ProgramFiles** environment variable. The `$env:` variable prefix can +be used from any PowerShell drive. + +``` +PS C:\> $env:ProgramFiles +C:\Program Files +``` + +You can also change the value of an environment variable using the `$env:` +variable prefix. Any changes made only pertain to the current PowerShell +session for as long as it is active. + +> [!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](../../Microsoft.PowerShell.Management/Get-ChildItem.md), +> `cd` is an alias for [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md). and `pwd` is +> an alias for [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md). + +## Getting environment variables + +This command lists all the environment variables in the current session. + +```powershell +Get-Item -Path Env: +``` + +You can use this command from any PowerShell drive. + +The Environment provider has no containers, so the above command has the +same effect when used with `Get-ChildItem`. + +```powershell +Get-ChildItem -Path Env: +``` + +### Get a selected environment variable + +This command gets the `WINDIR` environment Variable. + +```powershell +Get-ChildItem -Path Env:windir +``` + +You can also use the variable prefix format as well. + +```powershell +$env:windir +``` + +## Create an environment variable + +This command creates the `USERMODE` environment variable with a value of +"Non-Admin". The `-Path` parameter value creates the new item in the `Env:` +drive. The new environment variable is only usable in the current PowerShell +session for as long as it is active. + +```powershell +PS C:\> New-Item -Path Env: -Name USERMODE -Value Non-Admin +``` + +## Changing an environment variable + +### Rename an environment variable + +This command uses the `Rename-Item` cmdlet to change the name of the `USERMODE` +environment variable that you created to `USERROLE`. Do not change the name of +an environment variable that the system uses. Although these changes affect +only the current session, they might cause the system or a program to operate +incorrectly. + +```powershell +Rename-Item -Path Env:USERMODE -NewName USERROLE +``` + +### Change an environment variable + +This command uses the `Set-Item` cmdlet to change the value of the `USERROLE` +environment variable to "Administrator". + +```powershell +Set-Item -Path Env:USERROLE -Value Administrator +``` + +## Copy an environment variable + +This command copies the value of the `USERROLE` environment variable to the +`USERROLE2` environment Variable. + +```powershell +Copy-Item -Path Env:USERROLE -Destination Env:USERROLE2 +``` + +## Remove an environment variable + +This command deletes the `USERROLE2` environment variable from the current +session. + +```powershell +Remove-Item -Path Env:USERROLE2 +``` + +## Remove an environment variable with Clear-Item + +This command deletes the `USERROLE` environment variable by clearing its +value. + +```powershell +Clear-Item -Path Env:USERROLE +``` + +## 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](../Get-Help.md) command in a file system drive or use the `-Path` +parameter of [Get-Help](../Get-Help.md) to specify a file system drive. + +```powershell +Get-Help Get-ChildItem +``` + +```powershell +Get-Help Get-ChildItem -Path c: +``` + +{{Make provider specific>}} + +## See also + +[about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider.md new file mode 100644 index 000000000000..cdad55d19da2 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/Providers/about_FileSystem_Provider.md @@ -0,0 +1,650 @@ +--- +ms.date: 10/18/2018 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: FileSystem Provider +online version: http://go.microsoft.com/fwlink/?LinkId=821468 +--- +# FileSystem provider + +## Provider name + +FileSystem + +## Drives + +`C:`, `D:` ... + +## Capabilities + +**Filter**, **ShouldProcess** + +## Short description + +Provides access to files and directories. + +## Detailed description + +The PowerShell **FileSystem** provider lets you get, add, change, clear, and +delete files and directories in PowerShell. + +The **FileSystem** drives are a hierarchical namespace containing the +directories and files on your computer. A **FileSystem** drive can be a logical +or phsyical drive, directory, or mapped network share. + +The **FileSystem** provider supports the following cmdlets, which are covered +in this article. + +- [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) +- [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) +- [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) +- [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Get-ItemProperty](../../Microsoft.PowerShell.Management/Get-ItemProperty.md) +- [Set-ItemProperty](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) +- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) +- [Clear-ItemProperty](../../Microsoft.PowerShell.Management/Clear-ItemProperty.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Remove-ItemProperty](../../Microsoft.PowerShell.Management/Remove-ItemProperty.md) +- [Get-Acl](../../Microsoft.PowerShell.Security/Get-Acl.md) +- [Set-Acl](../../Microsoft.PowerShell.Security/Set-Acl.md) +- [Get-AuthenticodeSignature](../../Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md) +- [Set-AuthenticodeSignature](../../Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md) + +{{Make sure list is correct}} + +## Types exposed by this provider + +Files are instances of the `System.IO.FileInfo` class. Directories are +instances of the `System.IO.DirectoryInfo` class. + +{{change these into links to the classes}} + +## Navigating the FileSystem drives + +The **FileSystem** provider exposes its data stores by mapping any logical +drives on the computer as PowerShell drives. To work with a **FileSystem** +drive you can change your location to a drive uing the drive name followed +by a colon (`:`). + +```powershell +Set-Location C: +``` + +You can also work with the **FileSystem** provider from any other PowerShell +drive. To reference a file or directory from another location, use the drive name (`C:`, `D:`, ...) in the path. + +> [!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](../../Microsoft.PowerShell.Management/Get-ChildItem.md), +> `cd` is an alias for [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md). and `pwd` is +> an alias for [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md). + +## Getting files and directories + +The `Get-ChildItem` cmdlet returns all files and directories in the +current location. You can specify a different path to search and use built +in parameters to filter and control the recursion depth. + +```powershell +Get-ChildItem +``` + +To read more about cmdlet usage, see [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md). + +## Copying files and directories + +The `Copy-Item` cmdlet copies files and directories to a location you specify. +Parameters are available to filter and recurse, similar to `Get-ChildItem`. + +The following command copies all of the files and directories under the path +"C:\temp\" to the folder "C:\Windows\Temp". + +```powershell +Copy-Item -Path C:\temp\* -Destination C:\Windows\Temp -Recurse -File +``` + +`Copy-Item` overwrites files in the destination directory without prompting for +confirmation. + +This command copies the `a.txt` file from the `C:\a` directory to the `C:\a\bb` +directory. + +```powershell +Copy-Item -Path C:\a\a.txt -Destination C:\a\bb\a.txt +``` + +Copies all the directories and files in the `C:\a` directory to the `C:\c` +directory. If any of the directories to copy already exist in the destination +directory, the command will fail unless you specify the Force parameter. + +```powershell +Copy-Item -Path C:\a\* -Destination C:\c -Recurse +``` + +For more information, see [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md). + +## Moving files and directories + +This command moves the `c.txt` file in the `C:\a` directory to the `C:\a\aa` +directory: + +```powershell +Move-Item -Path C:\a\c.txt -Destination C:\a\aa +``` + +The command will not automatically overwrite an existing file that has the same +name. To force the cmdlet to overwrite an existing file, specify the Force +parameter. + +You cannot move a directory when that directory is the current location. When +you use `Move-Item` to move the directory at the current location, you see +this error. + +``` +C:\temp> Move-Item -Path C:\temp\ -Destination C:\Windows\Temp + +Move-Item : Cannot move item because the item at 'C:\temp\' is in use. +At line:1 char:1 ++ Move-Item C:\temp\ C:\temp2\ ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : InvalidOperation: (:) [Move-Item], PSInvalidOperationException + + FullyQualifiedErrorId : InvalidOperation,Microsoft.PowerShell.Commands.MoveItemCommand +``` + +## Managing file content + +### Get the content of a file + +This command gets the contents of the "Test.txt" file and displays them in the +console. + +```powershell +Get-Content -Path Test.txt +``` + +You can pipe the contents of the file to another cmdlet. For example, the +following command reads the contents of the `Test.txt` file and then supplies +them as input to the +[ConvertTo-Html](../../Microsoft.PowerShell.Utility/ConvertTo-Html.md) cmdlet: + +```powershell +Get-Content -Path Test.txt | ConvertTo-Html +``` + +### Add content to a file + +This command appends the "test content" string to the `Test.txt` file: + +```powershell +Add-Content -Path test.txt -Value "test content" +``` + +The existing content in the `Test.txt` file is not deleted. + +### Replace the content of a file + +This command replaces the contents of the `Test.txt` file with the "test +content" string: + +```powershell +Set-Content -Path test.txt -Value "test content" +``` + +It overwrites the contents of `Test.txt`. You can use the **Value** parameter +of the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to +add content to a file when you create it. + +### Loop through the contents of a file + +By default, the `Get-Content` cmdlet uses the end-of-line character as its +delimiter, so it gets a file as a collection of strings, with each line as one +string in the file. + +You can use the `-Delimiter` parameter to specify an alternate delimiter. If +you set it to the characters that denote the end of a section or the beginning +of the next section, you can split the file into logical parts. + +The first command gets the `Employees.txt` file and splits it into sections, +each of which ends with the words "End of Employee Record" and it saves it in +the `$e` variable. + +The second command uses array notation to get the first item in the collection +in `$e`. It uses an index of 0, because PowerShell arrays are zero-based. + +For more information about `Get-Content` cmdlet, see the help topic for the +[Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md). + +For more information about arrays, see [about_Arrays](../About/about_Arrays.md). + +```powershell +$e = Get-Content c:\test\employees.txt -Delimited "End Of Employee Record" +$e[0] +``` + +## Managing security descriptors + +### View the ACL for a file + +This command returns a +[System.Security.AccessControl.FileSecurity](/dotnet/api/system.security.accesscontrol.filesecurity) +object: + +```powershell +Get-Acl -Path test.txt | Format-List -Property * +``` + +For more information about this object, pipe the command to the +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet. Or, see +"[FileSecurity](/dotnet/api/system.security.accesscontrol.filesecurity) Class" in the +MSDN (Microsoft Developer Network) library. + +### Modify the ACL for a file + +### Create and set an ACL for a file + +## Creating files and directories + +### Create a directory + +This command creates the `logfiles` directory on the `C` drive: + +```powershell +New-Item -Path c:\ -Name logfiles -Type directory +``` + +PowerShell also includes a `mkdir` function (alias `md`) that uses the +[New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to +create a new directory. + +### Create a file + +This command creates the `log2.txt` file in the `C:\logfiles` directory and +then adds the "test log" string to the file: + +```powershell +New-Item -Path c:\logfiles -Name log2.txt -Type file +``` + +### Create a file with content + +Creates a file called `log2.txt` in the `C:\logfiles` directory and adds the +string "test log" to the file. + +```powershell +New-Item -Path c:\logfiles -Name log2.txt -Type file -Value "test log" +``` + +## Renaming files and directories + +### Rename a file + +This command renames the `a.txt` file in the `C:\a` directory to `b.txt`: + +```powershell +Rename-Item -Path c:\a\a.txt -NewName b.txt +``` + +### Rename a directory + +This command renames the `C:\a\cc` directory to `C:\a\dd`: + +```powershell +Rename-Item -Path c:\a\cc -NewName dd +``` + +## Deleting files and directories + +### Delete a file + +This command deletes the `Test.txt` file in the current directory: + +```powershell +Remove-Item -Path test.txt +``` + +### Delete files using wildcards + +This command deletes all the files in the current directory that have the +`.xml` file name extension: + +```powershell +Remove-Item -Path *.xml +``` + +## Starting a program by invoking an associated file + +### Invoke a file + +The first command uses the +[Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) cmdlet to +get information about local services. + +It pipes the information to the +[Export-Csv](../../Microsoft.PowerShell.Utility/Export-Csv.md) cmdlet and then +stores that information in the `Services.csv` file. + +The second command uses +[Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) to open the +`services.csv` file in the program associated with the `.csv` extension: + +```powershell +Get-Service | Export-Csv -Path services.csv +Invoke-Item -Path services.csv +``` + +## Getting files and folders with specified attributes + +### Get System files + +This command gets system files in the current directory and its subdirectories. + +It uses the `-File` parameter to get only files (not directories) and the +`-System` parameter to get only items with the "system" attribute. + +It uses the `-Recurse` parameter to get the items in the current directory and +all subdirectories. + +```powershell +Get-ChildItem -File -System -Recurse +``` + +### Get Hidden files + +This command gets all files, including hidden files, in the current directory. + +It uses the **Attributes** parameter with two values, `!Directory+Hidden`, +which gets hidden files, and `!Directory`, which gets all other files. + +```powershell +Get-ChildItem -Attributes !Directory,!Directory+Hidden +``` + +`dir -att !d,!d+h` is the equivalent of this command. + +### Get Compressed and Encrypted files + +This command gets files in the current directory that are either compressed or +encrypted. + +It uses the `-Attributes` parameter with two values, `Compressed` and +`Encrypted`. The values are separated by a comma `,` which represents the "OR" +operator. + +```powershell +Get-ChildItem -Attributes Compressed,Encrypted +``` + +## 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. + +## 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. + +### Encoding \ + +Specifies the file encoding. The default is ASCII. + +- **ASCII**: Uses the encoding for the ASCII (7-bit) character set. +- **BigEndianUnicode**: Encodes in UTF-16 format using the big-endian byte order. +- **String**: Uses the encoding type for a string. +- **Unicode**: Encodes in UTF-16 format using the little-endian byte order. +- **UTF7**: Encodes in UTF-7 format. +- **UTF8**: Encodes in UTF-8 format. +- **UTF8BOM**: Encodes in UTF-8 format with Byte Order Mark (BOM) +- **UF8NOBOM**: Encodes in UTF-8 format without Byte Order Mark (BOM) +- **UTF32**: Encodes in UTF-32 format. +- **Default**: Encodes in the default installed code page. +- **OEM**: Uses the default encoding for MS-DOS and console programs. +- **Unknown**: The encoding type is unknown or invalid. The data can be treated + as binary. + +#### Cmdlets supported + +- [Add-Content](../../Microsoft.PowerShell.Management/Add-Content.md) +- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) +- [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) + +### Delimiter \ + +Specifies the delimiter that +[Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) uses to +divide the file into objects while it reads. + +The default is `\n`, the end-of-line character. + +When reading a text file, +[Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) returns a +collection of string objects, each of which ends with the delimiter character. + +Entering a delimiter that does not exist in the file, +[Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) returns the +entire file as a single, un-delimited object. + +You can use this parameter to split a large file into smaller files by +specifying a file separator, such as "End of Example", as the delimiter. The +delimiter is preserved (not discarded) and becomes the last item in each file +section. + +> [!NOTE] +> Currently, when the value of the `-Delimiter` parameter is an empty string, +> [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) does not return anything. +> This is a known issue. To force [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) to return the entire +> file as a single, undelimited string, enter a value that does not exist in +> the file. + +#### Cmdlets supported + +- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) + +### Wait \ + +Waits for content to be appended to the file. If content is appended, it +returns the appended content. If the content has changed, it returns the entire +file. + +When waiting, +[Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) checks the +file once each second until you interrupt it, such as by pressing CTRL+C. + +#### Cmdlets supported + +- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) + +### Attributes \ + +Gets files and folders with the specified attributes. This parameter supports +all attributes and lets you specify complex combinations of attributes. + +The `-Attributes` parameter was introduced in Windows PowerShell 3.0. + +The `-Attributes` parameter supports the following attributes: + +- **Archive** +- **Compressed** +- **Device** +- **Directory** +- **Encrypted** +- **Hidden** +- **Normal** +- **NotContentIndexed** +- **Offline** +- **ReadOnly** +- **ReparsePoint** +- **SparseFile** +- **System** +- **Temporary** + +For a description of these attributes, see the +[FileAttributes](/dotnet/api/system.io.fileattributes) enumeration. + +Use the following operators to combine attributes. + +- `!` - NOT +- `+` - AND +- `,` - OR + +No spaces are permitted between an operator and its attribute. However, spaces +are permitted before commas. + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +### Directory \ + +Gets directories (folders). + +The `-Directory` parameter was introduced in Windows PowerShell 3.0. + +To get only directories, use the `-Directory` parameter and omit the `-File` +parameter. To exclude directories, use the `-File` parameter and omit the +`-Directory` parameter, or use the `-Attributes` parameter. + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +### File \ + +Gets files. + +The `-File` parameter was introduced in Windows PowerShell 3.0. + +To get only files, use the `-File` parameter and omit the `-Directory` +parameter. To exclude files, use the `-Directory` parameter and omit the +`-File` parameter, or use the `-Attributes` parameter. + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +### Hidden \ + +Gets only hidden files and directories (folders). By default, [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets only non-hidden items. + +The `-Hidden` parameter was introduced in Windows PowerShell 3.0. + +To get only hidden items, use the `-Hidden` parameter, its `h` or `ah` aliases, +or the **Hidden** value of the `-Attributes` parameter. To exclude hidden +items, omit the `-Hidden` parameter or use the `-Attributes` parameter. + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +### ReadOnly \ + +Gets only read-only files and directories (folders). + +The `-ReadOnly` parameter was introduced in Windows PowerShell 3.0. + +To get only read-only items, use the `-ReadOnly` parameter, its `ar` alias, or +the **ReadOnly** value of the `-Attributes` parameter. To exclude read-only +items, use the `-Attributes` parameter. + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +### System \ + +Gets only system files and directories (folders). + +The `-System` parameter was introduced in Windows PowerShell 3.0. + +To get only system files and folders, use the `-System` parameter, its `as` +alias, or the **System** value of the `-Attributes` parameter. To exclude +system files and folders, use the `-Attributes` parameter. + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +### NewerThan \ + +Returns `$True` when the `LastWriteTime` value of a file is greater than the +specified date. Otherwise, it returns `$False`. + +Enter a [DateTime](/dotnet/api/system.datetime) object, +such as one that the [Get-Date](../../Microsoft.PowerShell.Utility/Get-Date.md) +cmdlet returns, or a string that can be converted to a +[DateTime](/dotnet/api/system.datetime) object, such as +`"August 10, 2011 2:00 PM"`. + +#### Cmdlets supported + +- [Test-Path](../../Microsoft.PowerShell.Management/Test-Path.md) + +### OlderThan \ + +Returns `$True` when the `LastWriteTime` value of a file is less than the +specified date. Otherwise, it returns `$False`. + +Enter a [DateTime](/dotnet/api/system.datetime) object, +such as one that the [Get-Date](../../Microsoft.PowerShell.Utility/Get-Date.md) +cmdlet returns, or a string that can be converted to a +[DateTime](/dotnet/api/system.datetime) object, such as +`"August 10, 2011 2:00 PM"`. + +#### Cmdlets supported + +- [Test-Path](../../Microsoft.PowerShell.Management/Test-Path.md) + +### Stream \ + +Manages alternate data streams. Enter the stream name. Wildcards are permitted +only in [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) for and [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) commands +in a file system drive. + +#### Cmdlets supported + +- [Add-Content](../../Microsoft.PowerShell.Management/Add-Content.md) +- [Clear-Content](../../Microsoft.PowerShell.Management/Clear-Content.md) +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) +- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) + +### Raw \ + +Ignores newline characters. Returns contents as a single item. + +#### Cmdlets supported + +- [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) + +## 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](../Get-Help.md) command in a file system drive or use the `-Path` +parameter of [Get-Help](../Get-Help.md) to specify a file system drive. + +```powershell +Get-Help Get-ChildItem +``` + +```powershell +Get-Help Get-ChildItem -Path c: +``` + +{{Make provider specific>}} + +## See also + +[about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/about_Function_Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/about_Function_Provider.md new file mode 100644 index 000000000000..ffd04b47d0f2 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/Providers/about_Function_Provider.md @@ -0,0 +1,241 @@ +--- +ms.date: 10/18/2018 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: Function Provider +online version: http://go.microsoft.com/fwlink/?LinkId=834961 +--- +# Function provider + +## Provider name + +Function + +## Drives + +`Function:` + +## Capabilities + +**ShouldProcess** + +## Short description + +Provides access to the functions defined in PowerShell. + +## Detailed description + +The PowerShell **Function** provider lets you get, add, change, clear, and +delete the functions and filters in PowerShell. + +A function is a named block of code that performs an action. When you type the +function name, the code in the function runs. A filter is a named block of code +that establishes conditions for an action. You can type the name of the filter +in place of the condition, such as in a `Where-Object` command. + +The **Function** drive is a flat namespace that contains only the function +and filter objects. Neither functions nor filters have child items. + +The **Function** provider supports the following cmdlets, which are covered +in this article. + +- [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) +- [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) + +{{Make sure list is correct}} + +## Types exposed by this provider + +Each function is an instance of the +[System.Management.Automation.FunctionInfo](/dotnet/api/system.management.automation.functioninfo) +class. Each filter is an instance of the +[System.Management.Automation.FilterInfo](/dotnet/api/system.management.automation.filterinfo) +class. + +## Navigating the Function drive + +The **Function** provider exposes its data store in the `Function:` drive. To +work with functions, you can change your location to the `Function:` drive +(`Set-Location Function:`). Or, you can work from another PowerShell drive. To +reference a function from another location, use the drive name (`Function:`) in +the path. + +```powershell +Set-Location Function: +``` + +To return to a file system drive, type the drive name. For example, type: + +```powershell +Set-Location C: +``` + +You can also work with the **Function** provider from any other PowerShell +drive. To reference an function from another location, use the drive name +`Function:` in the path. + +> [!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](../../Microsoft.PowerShell.Management/Get-ChildItem.md), +> `cd` is an alias for [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md). and `pwd` is +> an alias for [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md). + +## Getting functions + +This command gets the list of all the functions in the current session. You can +use this command from any PowerShell drive. + +```powershell +Get-ChildItem -Path Function: +``` + +The Function provider has no containers, so the above command has the +same effect when used with `Get-ChildItem`. + +```powershell +Get-ChildItem -Path Function: +``` + +### Getting selected functions + +This command gets the `man` function from the `Function:` drive. It uses the +`Get-Item` cmdlet to get the function. The pipeline operator (`|`) sends the +result to `Format-Table`. The `-Wrap` parameter directs text that does not fit +on the line onto the next line. The `-Autosize` parameter resizes the table +columns to accommodate the text. + +```powershell +Get-Item -Path man | Format-Table -Wrap -Autosize +``` + +### Working with Function provider paths + +These commands both get the function named `c:`. The first command can be used +in any drive. The second command is used in the `Function:` drive. Because the +name ends in a colon, which is the syntax for a drive, you must qualify the +path with the drive name. Within the `Function:` drive, you can use either +format. In the second command, the dot (`.`) represents the current location. + +``` +PS C:\> Get-Item -Path Function:c: +PS Function:\> Get-Item -Path .\c: +``` + +## Creating a function + +This command uses the `New-Item` cmdlet to create a function called `Win32:`. +The expression in braces is the script block that is represented by the +function name. + +```powershell +New-Item -Path Function:Win32: -Value {Set-Location C:\Windows\System32} +``` + +You can also create a function by typing it at the PowerShell command line. For +example, tpe `Function:Win32: {Set-Location C:\Windows\System32}`. If you are +in the `Function:` drive, you can omit the drive name. + +## Deleting a function + +This command deletes the `more:` function from the current session. + +```powershell +Remove-Item Function:more: +``` + +## Changing a function + +This command uses the `Set-Item` cmdlet to change the `prompt` function so that +it displays the time before the path. + +```powershell +Set-Item -Path Function:prompt -Value { + 'PS '+ $(Get-Date -Format t) + " " + $(Get-Location) + '> ' + } +``` + +### Rename a function + +This command uses the `Rename-Item` cmdlet to change the name of the `help` +function to `gh`. + +```powershell +Rename-Item -Path Function:help -NewName gh +``` + +## Copying a function + +This command copies the `prompt` function to `oldPrompt`, effectively creating +a new name for the script block that is associated with the prompt function. +You can use this to save the original prompt function if you plan to change it. +The **Options** property of the new function has a value of `None`. To change +the value of the **Options** property, use `Set-Item`. + +```powershell +Copy-Item -Path Function:prompt -Destination Function:oldPrompt +``` + +## 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. + +## 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. + +### Options <[System.Management.Automation.ScopedItemOptions]> + +Determines the value of the **Options** property of a function. + +- `None`: No options. `None` is the default. +- `Constant`: The function cannot be deleted, and its properties cannot be + changed. `Constant` is available only when you are creating a function. + You cannot change the option of an existing function to `Constant`. +- `Private`: The function is visible only in the current scope +- (not in child scopes). +- `ReadOnly`: The properties of the function cannot be changed except by + using the `-Force` parameter. You can use `Remove-Item` to delete the + function. +- `AllScope`: The function is copied to any new scopes that are created. + +### Cmdlets supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) + +## 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](../Get-Help.md) command in a file system drive or use the `-Path` +parameter of [Get-Help](../Get-Help.md) to specify a file system drive. + +```powershell +Get-Help Get-ChildItem +``` + +```powershell +Get-Help Get-ChildItem -Path c: +``` + +{{Make provider specific>}} + +## See also + +[about_Functions](../About/about_Functions.md) + +[about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/about_Registry_Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/about_Registry_Provider.md new file mode 100644 index 000000000000..9398c76a3ff7 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/Providers/about_Registry_Provider.md @@ -0,0 +1,535 @@ +--- +ms.date: 10/18/2018 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: Registry Provider +online version: http://go.microsoft.com/fwlink/?LinkId=821468 +--- +# 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](../../Microsoft.PowerShell.Management/Get-Location.md) +- [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) +- [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) +- [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Get-ItemProperty](../../Microsoft.PowerShell.Management/Get-ItemProperty.md) +- [Set-ItemProperty](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) +- [Remove-ItemProperty](../../Microsoft.PowerShell.Management/Remove-ItemProperty.md) +- [Clear-ItemProperty](../../Microsoft.PowerShell.Management/Clear-ItemProperty.md) +- [Get-Acl](../../Microsoft.PowerShell.Security/Get-Acl.md) +- [Set-Acl](../../Microsoft.PowerShell.Security/Set-Acl.md) + +{{Make sure list is correct}} + +## Types exposed by this provider + +Registry keys are represented as instances of the +[Microsoft.Win32.RegistryKey](https://docs.microsoft.com/en-us/dotnet/api/microsoft.win32.registrykey) +class. Registry entries are represented as instances of the +[PSCustomObject](/dotnet/api/system.management.automation.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. + +```powershell +Set-Location HKLM: +``` + +To return to a file system drive, type the drive name. For example, type: + +```powershell +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. + +```powershell +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](../../Microsoft.PowerShell.Management/Get-ChildItem.md), +> `cd` is an alias for [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md). and `pwd` is +> an alias for [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md). + +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`. + +```powershell +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](/windows/desktop/sysinfo/structure-of-the-registry.md). + +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, SeAuditPrivilege, + SeChangeNotifyPrivilege...} + ServiceSidType : 1 + Start : 2 + Type : 272 +``` + +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](../../Microsoft.PowerShell.Management/Get-Item.md) +-[Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +## 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 **PSCustom** object 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. + +```powershell +$p = Get-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\Spooler +$p.DependOnService +``` + +```output +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. + +```powershell +Get-ItemPropertyValue -Path HKLM:\SOFTWARE\Microsoft\Wbem -Name BUILD +``` + +```output +17134.1 +``` + +For more information on the cmdlets used in this section, see the following +articles. + +- [Get-ItemProperty](../../Microsoft.PowerShell.Management/Get-ItemProperty.md) +- [Get-ItemPropertyValue](../../Microsoft.PowerShell.Management/Get-ItemProperty.md) + +## 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`. + +```powershell +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](../../Microsoft.PowerShell.Management/Set-Item.md) +- [Set-ItemProperty](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) + +## 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 to **Item Properties** +on a registry key that you specify. The following example creates a new +DWORD value on the ContosoCompany registry key. + +```powershell +$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](../../Microsoft.PowerShell.Management/New-ItemProperty.md). + +## 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. + +```powershell +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. + +```powershell +$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](../../Microsoft.PowerShell.Management/Copy-Item.md) +- [Copy-ItemProperty](../../Microsoft.PowerShell.Management/Copy-ItemProperty.md) + +## 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". + +```powershell +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". + +```powershell +$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](../../Microsoft.PowerShell.Management/Move-Item.md) +- [Move-ItemProperty](../../Microsoft.PowerShell.Management/Move-ItemProperty.md) + +## 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. + +```powershell +$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. + +```powershell +$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](../../Microsoft.PowerShell.Security/Get-Acl.md) +- [Set-Acl](../../Microsoft.PowerShell.Security/Set-Acl.md) + +## 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. + +```powershell +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. + +```powershell +Remove-Item -Path HKLM:\SOFTWARE\Contoso\* -Recurse +``` + +This command deletes the "ContosoTest" registry value from the "HKLM:\SOFTWARE\Contoso" registry key. + +```powershell +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](../../Microsoft.PowerShell.Management/Clear-Item.md) +- [Clear-ItemProperty](../../Microsoft.PowerShell.Management/Clear-ItemProperty.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Remove-ItemProperty](../../Microsoft.PowerShell.Management/Remove-ItemProperty.md) + +## 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. + +## 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 + +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](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) cmdlet. It is also available on the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) 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](../../Microsoft.PowerShell.Management/Set-Item.md) +- [Set-ItemProperty](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) + +## 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](../Get-Help.md) command in a file system drive or use the `-Path` +parameter of [Get-Help](../Get-Help.md) to specify a file system drive. + +```powershell +Get-Help Get-ChildItem +``` + +```powershell +Get-Help Get-ChildItem -Path C: +``` + +{{Make provider specific>}} + +## See also + + [about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/about_Variable_Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/about_Variable_Provider.md new file mode 100644 index 000000000000..7d62fd0161c9 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/Providers/about_Variable_Provider.md @@ -0,0 +1,283 @@ +--- +ms.date: 10/18/2018 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: Variable Provider +online version: http://go.microsoft.com/fwlink/?LinkId=834963 +--- +# Variable provider + +## Provider name + +Variable + +## Drives + +`Variable:` + +## Capabilities + +**ShouldProcess** + +## Short description + +Provides access to the PowerShell variables and to their values. + +## Detailed description + +The PowerShell **Variable** provider lets you get, add, change, clear, and +delete PowerShell variables in the current console. + +The PowerShell **Variable** provider supports the variables that PowerShell +creates, including the automatic variables, the preference variables, and the +variables that you create. + +The **Variable** drive is a flat namespace that contains only the variable +objects. The variables have no child items. + +The **Variable** provider supports the following cmdlets, which are covered +in this article. + +- [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) +- [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) + +{{Make sure list is correct}} + +PowerShell also includes a set of cmdlets designed especially to view and to +change variables. When you use **Variable** cmdlets, you do not need to specify +the `Variable:` drive in the name. This article does not cover working with +**Variable** cmdlets. + +- [Get-Variable](../../Microsoft.PowerShell.Utility/Get-Variable.md) +- [New-Variable](../../Microsoft.PowerShell.Utility/New-Variable.md) +- [Set-Variable](../../Microsoft.PowerShell.Utility/Set-Variable.md) +- [Remove-Variable](../../Microsoft.PowerShell.Utility/Remove-Variable.md) +- [Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) + +> [!NOTE] +> You can also use the PowShell expression parser to create, view, and change +> the values of variables without using the cmdlets. When working with variables +> directly, use a dollar sign (`$`) to identify the name as a variable and the +> assignment operator (`=`)to establish and change its value. For example, +> `$p = Get-Process` creates the `p` variable and stores the results of a +> `Get-Process` command in it. + +## Types exposed by this provider + +Variables can be one of several different types. Most variables will be +instances of the `PSVariable` class. Other variables and their types are +listed below. + +- The `?` variable is an instance of the `QuestionMarkVariable` class. +- The `null` variable is an instance of the `NullVariable` class. +- The maximum count variables are instances of the + `SessionStateCapacityVariable` class. +- `LocalVariable` instances contain information about current execution, + such as: + - `MyInvocation` + - `PSCommandPath` + - `PSScriptRoot` + - `PSBoundParameters` + - `args` + - `input` + +{{change these into links to the classes}} + +## Navigating the Variable drives + +The **Variable** provider exposes its data store in the `Variable:` drive. To +work with variables, you can change your location to the `Variable:` drive +(`Set-Location Variable:`), or you can work from any other PowerShell drive. To +reference a variable from another location, use the drive name (`Variable:`) in +the path. + +```powershell +Set-Location Variable: +``` + +To return to a file system drive, type the drive name. For example, type: + +```powershell +Set-Location C: +``` + +You can also work with the **Variable** provider from any other PowerShell +drive. To reference an variable from another location, use the drive name +`Variable:` in the path. + +> [!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](../../Microsoft.PowerShell.Management/Get-ChildItem.md), +> `cd` is an alias for [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md). and `pwd` is +> an alias for [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md). + +## Displaying the value of variables + +### Get all variables in the current session + +This command gets the list of all the variables and their values in the current +session. You can use this command from any PowerShell drive. + +```powershell +Get-ChildItem -Path Variable: +``` + +### Get variables using wildcards + +This command gets the variables with names that begin with "max". You can use +this command from any PowerShell drive. + +```powershell +Get-ChildItem -Path Variable:max* +``` + +### Get the value of the ? variable + +This command uses the `-LiteralPath` parameter of +[Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) to get +the value of the `?` variable from within the `Variable:` drive. The `?` is +a wildcard in paths, but `Get-ChildItem` does not attempt to resolve any +wildcards in the values of the `-LiteralPath` parameter. + +```powershell +Get-ChildItem -Literalpath ? +``` + +### Get ReadOnly and Constant variables + +This command gets the variables that have the values of `ReadOnly` or +`Constant` for their **Options** property. + +```powershell +Get-ChildItem -Path Variable: | Where-Object { + $_.options -Match "Constant" ` + -or $_.options -Match "ReadOnly" + } | Format-List -Property name, value, options +``` + +## Creating variables + +### Create a new variable + +This command creates the `services` variable and stores the results of a +`Get-Service` command in it. Because the current location is in the `Variable:` +drive, the value of the `-Path` parameter is a dot (`.`), which represents the +current location. + +The parentheses around the `Get-Service` command ensure that the command is +executed before the variable is created. Without the parentheses, the value of +the new variable is a "Get-Service" string. + +```powershell +New-Item -Path . -Name services -Value (Get-Service) +``` + +### Create a variable using an absolute path + +This command creates a `services` variable and stores the result of a +`Get-Service` command in it. + +```powershell +New-Item -Path Variable:services -Value Get-Service +``` + + To create a variable without a value, omit the assignment operator. + +## Changing variables + +### Rename a variable + +This command uses the `Rename-Item` cmdlet to change the name of the `a` +variable to `processes`. + +```powershell +Rename-Item -Path Variable:a -NewName processes +``` + +### Change the value of a variable + +This command uses the `Set-Item` cmdlet to change the value of the +`ErrorActionPreference` variable to "Stop". + +```powershell +Set-Item -Path Variable:ErrorActionPreference -Value Stop +``` + +## Copy a variable + +This command uses the `Copy-Item` cmdlet to copy the `processes` variable to +`old_processes`. This creates a new variable named `old_processes` that has the +same value as the `processes` variable. + +```powershell +Copy-Item -Path Variable:processes -Destination Variable:old_processes +``` + +## Delete a variable + +This command deletes the `serv` variable from the current session. You can use +this command in any PowerShell drive. + +```powershell +Remove-Variable -Path Variable:serv +``` + +### Delete variables using the -Force parameter + +This command deletes all variables from the current session except for the +variables whose **Options** property has a value of `Constant`. Without the +`-Force` parameter, the command does not delete variables whose **Options** +property has a value of `ReadOnly`. + +```powershell +Remove-Item Variable:* -Force +``` + +## Setting the value of a variable to NULL + +This command uses the `Clear-Item` cmdlet to change the value of the +`processes` variable to NULL. + +```powershell +Clear-Item -Path Variable:processes +``` + +## 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](../Get-Help.md) command in a file system drive or use the `-Path` +parameter of [Get-Help](../Get-Help.md) to specify a file system drive. + +```powershell +Get-Help Get-ChildItem +``` + +```powershell +Get-Help Get-ChildItem -Path c: +``` + +{{Make provider specific>}} + +## See also + +[about_Variables](../About/about_Variables.md) + +[about_Automatic_Variables](../About/about_Automatic_Variables.md) + +[about_Providers](../About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Add-Content.md b/reference/6/Microsoft.PowerShell.Management/Add-Content.md index c486b2b0670b..ae055f9c9f20 100644 --- a/reference/6/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Add-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 11/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821565 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Add-Content --- - # Add-Content ## SYNOPSIS @@ -18,7 +17,7 @@ Adds content to the specified items, such as adding words to a file. ### Path (Default) -```powershell +``` Add-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -26,7 +25,7 @@ Add-Content [-Value] [-PassThru] [-Path] [-Filter ### LiteralPath -```powershell +``` Add-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -34,7 +33,7 @@ Add-Content [-Value] [-PassThru] -LiteralPath [-Filter Add-Content -Path "*.txt" -Exclude "help*" -Value "END" +Add-Content -Path "*.txt" -Exclude "help*" -Value "END" ``` This command adds "END" to all text files in the current directory, except for those with file names that begin with "help". @@ -50,37 +49,37 @@ This command adds "END" to all text files in the current directory, except for t ### Example 2: Add a date to the end of the specified files ```powershell -PS C:\> Add-Content -Path "file1.log", "file2.log" -Value (Get-Date) -PassThru +Add-Content -Path "file1.log", "file2.log" -Value (Get-Date) -PassThru ``` This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. -The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. +The command uses the `Get-Date` cmdlet to get the date, and it uses the Value parameter to pass the date to `Add-Content`. The PassThru parameter passes an object representing the added content through the pipeline. Because there is no other cmdlet to receive the passed object, it is displayed at the command line. ### Example 3: Add the contents of a specified file to another file ```powershell -PS C:\> Add-Content -Path "monthly.txt" -Value (Get-Content "c:\rec1\weekly.txt") +Add-Content -Path "monthly.txt" -Value (Get-Content "c:\rec1\weekly.txt") ``` This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. -It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to Add-Content. -The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. +It uses the `Get-Content` cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to `Add-Content`. +The parentheses ensure that the `Get-Content` command is complete before the `Add-Content` command begins. -You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. -In that case, the command would be "Add-Content -Path monthly.txt -Value $w". +You can also copy the content of Weekly.txt to a variable, such as `$w`, and then use the Value parameter to pass the variable to `Add-Content`. +In that case, the command would be `Add-Content -Path monthly.txt -Value $w`. ### Example 4: Create a new file and copy content ```powershell -PS C:\> Add-Content -Value (Get-Content "test.log") -Path "C:\Tests\logs\test134.log" +Add-Content -Value (Get-Content "test.log") -Path "C:\Tests\logs\test134.log" ``` This command creates a new file and copies the content of an existing file to the newly created file. -This command uses the Add-Content cmdlet to add the content. -The value of the Value parameter is a Get-Content command that gets content from an existing file, Test.log. +This command uses the `Add-Content` cmdlet to add the content. +The value of the Value parameter is a `Get-Content` command that gets content from an existing file, Test.log. The value of the path parameter is a path that must exist when the command runs. In this example, C:\Tests\logs directory exists. @@ -118,7 +117,7 @@ Accept wildcard characters: False Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with PowerShell. @@ -136,22 +135,26 @@ Accept wildcard characters: False ``` ### -Encoding -Specifies the encoding that this cmdlet applies to the content. - -The acceptable values for this parameter are: - -- Unknown -- String -- Unicode -- Byte -- BigEndianUnicode -- UTF8 -- UTF7 -- UTF32 -- Ascii -- Default -- Oem -- BigEndianUTF32 + +Specifies the file encoding. The default is ASCII. + +Valid values are: + +- **ASCII**: Uses the encoding for the ASCII (7-bit) character set. +- **BigEndianUnicode**: Encodes in UTF-16 format using the big-endian byte order. +- **Default**: Encodes using the default value: ASCII. +- **OEM**: Uses the default encoding for MS-DOS and console programs. +- **Byte**: Encodes a set of characters into a sequence of bytes. +- **String**: Uses the encoding type for a string. +- **Unicode**: Encodes in UTF-16 format using the little-endian byte order. +- **UTF7**: Encodes in UTF-7 format. +- **UTF8**: Encodes in UTF-8 format. +- **UTF8BOM**: Encodes in UTF-8 format with Byte Order Mark (BOM) +- **UF8NOBOM**: Encodes in UTF-8 format without Byte Order Mark (BOM) +- **UTF32**: Encodes in UTF-32 format. +- **Unknown**: The encoding type is unknown or invalid; the data can be treated as binary. + +Encoding is a dynamic parameter that the FileSystem provider adds to the `Add-Content` cmdlet. This parameter works only in file system drives. ```yaml Type: FileSystemCmdletProviderEncoding @@ -205,7 +208,9 @@ Accept wildcard characters: True ``` ### -Force + Overrides the read-only attribute, allowing you to add content to a read-only file. +For example, **Force** will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions. ```yaml Type: SwitchParameter @@ -259,6 +264,7 @@ Accept wildcard characters: False ``` ### -NoNewline + Indicates that this cmdlet does not add a new line/carriage return to the content. The string representations of the input objects are concatenated to form the output. @@ -295,6 +301,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to the items that receive the additional content. Wildcards are permitted. If you specify multiple paths, use commas to separate the paths. @@ -312,16 +319,17 @@ Accept wildcard characters: True ``` ### -Stream + Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates it. Wildcard characters are not supported. -Stream is a dynamic parameter that the FileSystem provider adds to **Add-Content**. +Stream is a dynamic parameter that the FileSystem provider adds to `Add-Content`. This parameter works only in file system drives. -You can use the **Add-Content** cmdlet to change the content of the Zone.Identifier alternate data stream. +You can use the `Add-Content` cmdlet to change the content of the Zone.Identifier alternate data stream. However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. -If you verify that a downloaded file is safe, use the Unblock-File cmdlet. +If you verify that a downloaded file is safe, use the `Unblock-File` cmdlet. This parameter was introduced in PowerShell 3.0. @@ -338,6 +346,7 @@ Accept wildcard characters: False ``` ### -UseTransaction + Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see Includes the command in the active transaction. @@ -359,9 +368,9 @@ Accept wildcard characters: False ### -Value Specifies the content to be added. -Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that Get-Date generates. +Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that `Get-Date` generates. -You cannot specify the contents of a file by typing its path, because the path is just a string, but you can use a Get-Content command to get the content and pass it to the Value parameter. +You cannot specify the contents of a file by typing its path, because the path is just a string, but you can use a `Get-Content` command to get the content and pass it to the Value parameter. ```yaml Type: Object[] @@ -376,6 +385,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -393,32 +403,32 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS -### System.Object +### System.Object, System.Management.Automation.PSCredential -You can pipe the objects to be added by Add-Content. +You can pipe values, paths, or credentials to `Set-Content`. ## OUTPUTS ### None or System.String -When you use the Passthru parameter, Add-Content generates a System.String object representing the content. +When you use the **Passthru** parameter, `Add-Content` generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. +When you pipe an object to `Add-Content`, the object is converted to a string before it is added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. -You can also refer to Add-Content by its built-in alias, "ac". For more information, see about_Aliases. +You can also refer to `Add-Content` by its built-in alias, "ac". For more information, see about_Aliases. -The Add-Content cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type "Get-PsProvider". -For more information, see about_Providers. +The `Add-Content` cmdlet is designed to work with the data exposed by any provider. +To list the providers available in your session, type `Get-PsProvider`. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Management/Clear-Content.md b/reference/6/Microsoft.PowerShell.Management/Clear-Content.md index 12bc2f9c2eba..87b808b92019 100644 --- a/reference/6/Microsoft.PowerShell.Management/Clear-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Clear-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,55 +7,85 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821567 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Clear-Content --- - # Clear-Content ## SYNOPSIS + Deletes the contents of an item, but does not delete the item. ## SYNTAX ### Path (Default) + ``` Clear-Content [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Stream ] [] ``` ### LiteralPath + ``` Clear-Content -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Stream ] [] ``` ## DESCRIPTION -The **Clear-Content** cmdlet deletes the contents of an item, such as deleting the text from a file, but it does not delete the item. + +The `Clear-Content` cmdlet deletes the contents of an item, such as deleting the text from a file, but it does not delete the item. As a result, the item exists, but it is empty. -The **Clear-Content** is similar to Clear-Item, but it works on items with contents, instead of items with values. +The `Clear-Content` is similar to `Clear-Item`, but it works on items with contents, instead of items with values. ## EXAMPLES ### Example 1: Delete all content from a directory -``` -PS C:\> Clear-Content "..\SmpUsers\*\init.txt" + +```powershell +Clear-Content "..\SmpUsers\*\init.txt" ``` This command deletes all of the content from the "init.txt" files in all subdirectories of the SmpUsers directory. The files are not deleted, but they are empty. ### Example 2: Delete content of all files with a wildcard -``` -PS C:\> Clear-Content -Path "*" -Filter "*.log" -Force + +```powershell +Clear-Content -Path "*" -Filter "*.log" -Force ``` This command deletes the contents of all files in the current directory with the ".log" file name extension, including files with the read-only attribute. The asterisk (*) in the path represents all items in the current directory. -The *Force* parameter makes the command effective on read-only files. +The **Force** parameter makes the command effective on read-only files. Using a filter to restrict the command to files with the .log file name extension instead of specifying *.log in the path makes the operation faster. +### Example 3: Clear all data from a stream + +This example shows how the `Clear-Content` cmdlet clears the content from an alternate data stream while leaving the stream intact. + +The first command uses the `Get-Content` cmdlet to get the content of the Zone.Identifier stream in the Copy-Script.ps1 file, which was downloaded from the Internet. + +The second command uses the `Clear-Content` cmdlet to clear the content. + +The third command repeats the first command. It verifies that the content is cleared, but the stream remains. If the stream were deleted, the command would generate an error. + +You can use a method like this one to clear the content of an alternate data stream. However, it is not the recommended way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the `Unblock-File` cmdlet. + +``` +PS C:\> Get-Content C:\Test\Copy-Script.ps1 -Stream Zone.Identifier + +[ZoneTransfer] +ZoneId=3 + +PS C:\>Clear-Content C:\Test\Copy-Script.ps1 -Stream Zone.Identifier + +PS C:\>Get-Content C:\Test\Copy-Script.ps1 -Stream Zone.Identifier +PS C:\> +``` + ## PARAMETERS ### -Stream -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the **Get-Credential** cmdlet. + +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with PowerShell. @@ -73,10 +103,11 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with PowerShell. @@ -94,8 +125,9 @@ Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, strings that this cmdlet omits from the path to the content. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. @@ -112,8 +144,9 @@ Accept wildcard characters: False ``` ### -Filter + Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having PowerShell filter the objects after they are retrieved. @@ -130,6 +163,7 @@ Accept wildcard characters: False ``` ### -Force + Forces the command to run without asking for user confirmation. ```yaml @@ -145,8 +179,9 @@ Accept wildcard characters: False ``` ### -Include + Specifies, as a string array, content that this cmdlet clears. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. @@ -163,8 +198,9 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies the paths to the items from which content is deleted. -Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell having PowerShell not to interpret any characters as escape sequences. @@ -182,6 +218,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the paths to the items from which content is deleted. Wildcards are permitted. The paths must be paths to items, not to containers. @@ -202,6 +239,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -217,6 +255,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -233,6 +272,7 @@ Accept wildcard characters: False ``` ### -UseTransaction + Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see Includes the command in the active transaction. @@ -252,33 +292,29 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### None -You cannot pipe objects to **Clear-Content**. + +You cannot pipe objects to `Clear-Content`. ## OUTPUTS ### None + This cmdlet does not return any objects. ## NOTES -* You can also refer to **Clear-Content** by its built-in alias, "clc". For more information, see about_Aliases. - If you omit the *Path* parameter name, the value of the *Path* parameter must be the first parameter in the command. -For instance, `Clear-Content c:\mydir\*.txt`. -If you include the parameter name, you can list the parameters in any order. +You can use `Clear-Content` with the PowerShell FileSystem provider and with other providers that manipulate content. +To clear items that are not considered to be content, such as items managed by the PowerShell Certificate or Registry providers, use `Clear-Item`. - You can use **Clear-Content** with the PowerShell FileSystem provider and with other providers that manipulate content. -To clear items that are not considered to be content, such as items managed by the PowerShell Certificate or Registry providers, use Clear-Item. - - The **Clear-Content** cmdlet is designed to work with the data exposed by any provider. +The `Clear-Content` cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. -For more information, see about_Providers. - -* +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Management/Clear-Item.md b/reference/6/Microsoft.PowerShell.Management/Clear-Item.md index cb78248812d9..4f77f772f308 100644 --- a/reference/6/Microsoft.PowerShell.Management/Clear-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Clear-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,69 +7,79 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821569 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Clear-Item --- - # Clear-Item ## SYNOPSIS + Clears the contents of an item, but does not delete the item. ## SYNTAX ### Path (Default) + ``` Clear-Item [-Path] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ### LiteralPath + ``` Clear-Item -LiteralPath [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ## DESCRIPTION -The **Clear-Item** cmdlet clears the content of an item, but it does not delete the item. -For example, the **Clear-Item** cmdlet can delete the value of a variable, but it does not delete the variable. + +The `Clear-Item` cmdlet clears the content of an item, but it does not delete the item. +For example, the `Clear-Item` cmdlet can delete the value of a variable, but it does not delete the variable. The value that used to represent a cleared item is defined by each PowerShell provider. -This cmdlet is similar to Clear-Content, but it works on aliases and variables, instead of files. +This cmdlet is similar to `Clear-Content`, but it works on aliases and variables, instead of files. ## EXAMPLES ### Example 1: Clear the value of a variable -``` -PS C:\> Clear-Item Variable:TestVar1 --or- -PS C:> Set-location Variable: -PS Variable:\> Clear-Item TestVar1 -``` -This command clears the value of the variable named TestVar1. -The variable remains and is valid, but its value is set to null. -The variable name is prefixed with Variable: to indicate the PowerShell Variable provider. +This command clears the value of the variable named `TestVar1`. +The variable remains and is valid, but its value is set to `$null`. +The variable name is prefixed with `Variable:` to indicate the PowerShell Variable provider. -The alternate commands show that, to get the same result, you can switch to the PowerShell Variable: drive and then run the **Clear-Item** command. +The alternate commands show that, to get the same result, you can switch to the PowerShell `Variable:` drive and then run the `Clear-Item` command. -### Example 2: Clear all registry entries +```powershell +Clear-Item Variable:TestVar1 ``` -PS C:\> Clear-Item HKLM:\Software\MyCompany\MyKey -Confirm + ``` +Set-location Variable: +PS Variable:\> Clear-Item TestVar1 +``` + +### Example 2: Clear all registry entries -This command clears all registry entries in the MyKey subkey, but only after prompting you to confirm your intent. -It does not delete the MyKey subkey or affect any other registry keys or entries. +This command clears all registry entries in the "MyKey" subkey, but only after prompting you to confirm your intent. +It does not delete the "MyKey" subkey or affect any other registry keys or entries. You can use the **Include** and **Exclude** parameters to identify particular registry keys, but you cannot use them to identify registry entries. -To delete particular registry entries, use the Remove-ItemProperty cmdlet. -To delete the value of a registry entry, use the Clear-ItemPropertycmdlet. + +- To delete particular registry entries, use the `Remove-ItemProperty` cmdlet. +- To delete the value of a registry entry, use the `Clear-ItemPropertycmdlet`. + +```powershell +Clear-Item HKLM:\Software\MyCompany\MyKey -Confirm +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -78,16 +88,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, items to exclude. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +Wildcard characters are permitted. ```yaml Type: String[] @@ -98,14 +109,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects, rather than having PowerShell filter the objects after they are retrieved. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -116,15 +129,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Indicates that the cmdlet clears items that cannot otherwise be changed, such as read- only aliases. The cmdlet cannot clear constants. Implementation varies from provider to provider. -For more information, see about_Providers. -The cmdlet cannot override security restrictions, even when the *Force* parameter is used. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +The cmdlet cannot override security restrictions, even when the **Force** parameter is used. ```yaml Type: SwitchParameter @@ -133,16 +147,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include + Specifies, as a string array, items to that this cmdlet clears. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -153,15 +168,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath + Specifies the path to the items being cleared. -Unlike *Path*, the value of the *LiteralPath* parameter is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell *wps_2* not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -176,6 +192,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to the items being cleared. Wildcards are permitted. This parameter is required, but the parameter name (Path) is optional. @@ -193,6 +210,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -208,6 +226,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -223,52 +242,36 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a path string to this cmdlet. ## OUTPUTS ### None + This cmdlet does not generate any output. ## NOTES -* The **Clear-Item** cmdlet is supported only by several PowerShell providers, including the Alias, Environment, Function, Registry, and Variable providers. As such, you can use **Clear-Item** to delete the content of items in the provider namespaces. - You cannot use **Clear-Item** to delete the contents of a file, because the PowerShell FileSystem provider does not support this cmdlet. -To clear files, use the **Clear-Content**. +- The `Clear-Item` cmdlet is supported only by several PowerShell providers, including the Alias, Environment, Function, Registry, and Variable providers. As such, you can use `Clear-Item` to delete the content of items in the provider namespaces. + +- You cannot use `Clear-Item` to delete the contents of a file, because the PowerShell FileSystem provider does not support this cmdlet. + To clear files, use the `Clear-Content`. - You can also refer to **Clear-Item** by its built-in alias, cli. -For more information, type `Get-Help about_Aliases`. +- You can also refer to `Clear-Item` by its built-in alias, `cli`. + For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - The Clear-Item cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type "Get-PsProvider". -For more information, see about_Providers. +- The `Clear-Item` cmdlet is designed to work with the data exposed by any provider. + To list the providers available in your session, type `Get-PsProvider`. -* + For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS @@ -286,4 +289,6 @@ For more information, see about_Providers. [Rename-Item](Rename-Item.md) -[Set-Item](Set-Item.md) \ No newline at end of file +[Set-Item](Set-Item.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Clear-ItemProperty.md b/reference/6/Microsoft.PowerShell.Management/Clear-ItemProperty.md index 166503d3f03f..b521e3de77ac 100644 --- a/reference/6/Microsoft.PowerShell.Management/Clear-ItemProperty.md +++ b/reference/6/Microsoft.PowerShell.Management/Clear-ItemProperty.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821570 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Clear-ItemProperty --- - # Clear-ItemProperty ## SYNOPSIS + Clears the value of a property but does not delete the property. ## SYNTAX ### Path (Default) + ``` Clear-ItemProperty [-Path] [-Name] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -24,6 +25,7 @@ Clear-ItemProperty [-Path] [-Name] [-PassThru] [-Force] [-Fi ``` ### LiteralPath + ``` Clear-ItemProperty -LiteralPath [-Name] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -32,31 +34,35 @@ Clear-ItemProperty -LiteralPath [-Name] [-PassThru] [-Force] ``` ## DESCRIPTION -The **Clear-ItemProperty** cmdlet clears the value of a property, but it does not delete the property. + +The `Clear-ItemProperty` cmdlet clears the value of a property, but it does not delete the property. You can use this cmdlet to delete the data from a registry value. ## EXAMPLES ### Example 1: Clear the value of registry key -``` -PS C:\> Clear-ItemProperty -Path "HKLM:\Software\MyCompany\MyApp" -Name "Options" -``` -This command clear the data in the Options registry value in the MyApp subkey of HKEY_LOCAL_MACHINE\Software\MyCompany. +This command clear the data in the "Options" registry value in the "MyApp" subkey of "HKEY_LOCAL_MACHINE\Software\MyCompany". + +Because the command is being issued from a file system drive (`C:`), it uses the fully qualified path to the `HKLM:` drive and the "Software\MyCompany\MyApp" subkey. +It uses the **Name** parameter to specify the "Options" value. -Because the command is being issued from a file system drive (C:), it uses the fully qualified path to the HKLM: drive and the Software\MyCompany\MyApp subkey. -It uses the *Name* parameter to specify the Options value. +```powershell +Clear-ItemProperty -Path "HKLM:\Software\MyCompany\MyApp" -Name "Options" +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -65,16 +71,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, an item or items that this cmdlet excludes. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt or s*. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -85,13 +92,15 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml @@ -103,13 +112,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Indicates that this cmdlet deletes properties from items that cannot otherwise be accessed by the user. Implementation varies from provider to provider. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml Type: SwitchParameter @@ -118,12 +128,13 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include + Specifies, as a string array, an item or items that this cmdlet clears. The value of this parameter qualifies the *Path* parameter. Enter a path element or pattern, such as *.txt. @@ -142,8 +153,9 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies the path to the property being cleared. -Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -161,6 +173,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the property to be cleared, such as the name of a registry value. Wildcards are not permitted. @@ -177,6 +190,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. @@ -193,6 +207,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to the property being cleared. Wildcards are permitted. @@ -209,6 +224,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -224,6 +240,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -239,51 +256,34 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a path string to this cmdlet. ## OUTPUTS ### None or System.Management.Automation.PSCustomObject -When you use the *PassThru* parameter, **Clear-ItemProperty** generates a **PSCustomObject** object that represents the cleared item property. + +When you use the *PassThru* parameter, `Clear-ItemProperty` generates a **PSCustomObject** object that represents the cleared item property. Otherwise, this cmdlet does not generate any output. ## NOTES -* You can use **Clear-ItemProperty** to delete the data in registry values without deleting the value. If the data type of the value is Binary or DWORD, clearing the data sets the value to zero. Otherwise, the value is empty. - You can also refer to **Clear-ItemProperty** by its built-in alias, clp. +- You can use `Clear-ItemProperty` to delete the data in registry values without deleting the value. If the data type of the value is Binary or DWORD, clearing the data sets the value to zero. Otherwise, the value is empty. + +You can also refer to `Clear-ItemProperty` by its built-in alias, clp. For more information, see about_Aliases. - The **Clear-ItemProperty** cmdlet is designed to work with the data exposed by any provider. +The `Clear-ItemProperty` cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. -* - ## RELATED LINKS [Copy-ItemProperty](Copy-ItemProperty.md) @@ -294,4 +294,6 @@ For more information, see about_Providers. [New-ItemProperty](New-ItemProperty.md) -[Rename-ItemProperty](Rename-ItemProperty.md) \ No newline at end of file +[Rename-ItemProperty](Rename-ItemProperty.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Copy-Item.md b/reference/6/Microsoft.PowerShell.Management/Copy-Item.md index bc0afa8c20ff..a42e6d9fb5d6 100644 --- a/reference/6/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Copy-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821574 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Copy-Item --- - # Copy-Item ## SYNOPSIS + Copies an item from one location to another. ## SYNTAX ### Path (Default) + ``` Copy-Item [-Path] [[-Destination] ] [-Container] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Recurse] [-PassThru] [-Credential ] @@ -23,6 +24,7 @@ Copy-Item [-Path] [[-Destination] ] [-Container] [-Force] [-F ``` ### LiteralPath + ``` Copy-Item -LiteralPath [[-Destination] ] [-Container] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Recurse] [-PassThru] [-Credential ] @@ -30,7 +32,8 @@ Copy-Item -LiteralPath [[-Destination] ] [-Container] [-Force ``` ## DESCRIPTION -The **Copy-Item** cmdlet copies an item from one location to another location in the same namespace. + +The `Copy-Item` cmdlet copies an item from one location to another location in the same namespace. For instance, it can copy a file to a folder, but it cannot copy a file to a certificate drive. This cmdlet does not cut or delete the items being copied. @@ -38,127 +41,139 @@ The particular items that the cmdlet can copy depend on the PowerShell provider For instance, it can copy files and directories in a file system drive and registry keys and entries in the registry drive. This cmdlet can copy and rename items in the same command. -To rename an item, enter the new name in the value of the *Destination* parameter. -To rename an item and not copy it, use the Rename-Item cmdlet. +To rename an item, enter the new name in the value of the **Destination** parameter. +To rename an item and not copy it, use the `Rename-Item` cmdlet. ## EXAMPLES ### Example 1: Copy a file to the specified directory -```powershell -PS C:\> Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation" -``` -This command copies the mar1604.log.txt file to the C:\Presentation directory. +This command copies the "mar1604.log.txt" file to the "C:\Presentation" directory. The command does not delete the original file. -### Example 2: Copy the contents of a directory to another directory ```powershell -PS C:\> Copy-Item "C:\Logfiles" -Destination "C:\Drawings" -Recurse +Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation" ``` -This command copies the entire contents of the Logfiles directory into the Drawings directory. -If the LogFiles directory contains files in subdirectories, those subdirectories are copied with their file trees intact. -The *Container* parameter is set to true by default. +### Example 2: Copy the contents of a directory to another directory + +This command copies the entire contents of the "Logfiles" directory into the "Drawings" directory. +If the "LogFiles" directory contains files in subdirectories, those subdirectories are copied with their file trees intact. +The **Container** parameter is set to "true" by default. This preserves the directory structure. -### Example 3: Copy the contents of a directory to another directory and create the destination directory if it does not exist ```powershell -PS C:\> Copy-Item C:\Logfiles -Destination C:\Drawings\Logs -Recurse +Copy-Item "C:\Logfiles" -Destination "C:\Drawings" -Recurse ``` -This command copies the contents of the C:\Logfiles directory to the C:\Drawings\Logs directory. -It creates the \Logs subdirectory if it does not already exist. +### Example 3: Copy the contents of a directory to another directory and create the destination directory if it does not exist + +This command copies the contents of the "C:\Logfiles" directory to the "C:\Drawings\Logs" directory. +It creates the "\Logs" subdirectory if it does not already exist. -### Example 4: Copy a file to the specified directory and rename the file ```powershell -PS C:\> Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt" +Copy-Item C:\Logfiles -Destination C:\Drawings\Logs -Recurse ``` -This command uses the **Copy-Item** cmdlet to copy the Get-Widget.ps1 script from the \\\\Server01\Share directory to the \\\\Server12\ScriptArchive directory. -As part of the copy operation, the command also changes the item name from Get-Widget.ps1 to Get-Widget.ps1.txt, so it can be attached to email messages. +### Example 4: Copy a file to the specified directory and rename the file + +This command uses the `Copy-Item` cmdlet to copy the "Get-Widget.ps1" script from the "\\\\Server01\Share" directory to the "\\\\Server12\ScriptArchive" directory. +As part of the copy operation, the command also changes the item name from "Get-Widget.ps1" to "Get-Widget.ps1.txt", so it can be attached to email messages. -### Example 5: Copy a file to a remote computer ```powershell -PS C:\> $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" -PS C:\> Copy-Item "D:\Folder001\test.log" -Destination "C:\Folder001_Copy\" -ToSession $Session +Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt" ``` -The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session. +### Example 5: Copy a file to a remote computer -The second command uses the **Copy-Item** cmdlet to copy test.log from the D:\Folder001 folder to the C:\Folder001_Copy folder on the remote computer using the session information stored in the $Session variable. +The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. + +The second command uses the `Copy-Item` cmdlet to copy "test.log" from the "D:\Folder001" folder to the "C:\Folder001_Copy" folder on the remote computer using the session information stored in the `$Session` variable. This command does not delete the original file. -### Example 6: Copy the entire contents of a folder to a remote computer ```powershell -PS C:\> $Session = New-PSSession -ComputerName "Server02" -Credential "Contoso\PattiFul" -PS C:\> Copy-Item "D:\Folder002\" -Destination "C:\Folder002_Copy\" -ToSession $Session +$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" +Copy-Item "D:\Folder001\test.log" -Destination "C:\Folder001_Copy\" -ToSession $Session ``` -The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session. +### Example 6: Copy the entire contents of a folder to a remote computer + +The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the **Copy-Item** cmdlet to copy the entire contents from the D:\Folder002 folder to the C:\Folder002_Copy directory on the remote computer using the session information stored in the $Session variable. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the "D:\Folder002" folder to the "C:\Folder002_Copy" directory on the remote computer using the session information stored in the `$Session` variable. The subfolders are copied with their file trees intact. -### Example 7: Recursively copy the entire contents of a folder to a remote computer ```powershell -PS C:\> $Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\PattiFul" -PS C:\> Copy-Item "D:\Folder003\" -Destination "C:\Folder003_Copy\" -ToSession $Session -Recurse +$Session = New-PSSession -ComputerName "Server02" -Credential "Contoso\PattiFul" +Copy-Item "D:\Folder002\" -Destination "C:\Folder002_Copy\" -ToSession $Session ``` -The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session. +### Example 7: Recursively copy the entire contents of a folder to a remote computer + +The first command creates a session to the remote computer named Server01 with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the **Copy-Item** cmdlet to copy the entire contents from the D:\Folder003 folder to the C:\Folder003_Copy directory on the remote computer using the session information stored in the $Session variable. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the "D:\Folder003" folder to the "C:\Folder003_Copy" directory on the remote computer using the session information stored in the `$Session` variable. The subfolders are copied with their file trees intact. -Since this command uses the *Recurse* parameter, the operation creates the Folder003_Copy folder if it does not already exist. +Since this command uses the **Recurse** parameter, the operation creates the "Folder003_Copy" folder if it does not already exist. -### Example 8: Copy a file to a remote computer and then rename the file ```powershell -PS C:\> $Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\PattiFul" -PS C:\> Copy-Item "D:\Folder004\scriptingexample.ps1" -Destination "C:\Folder004_Copy\scriptingexample_copy.ps1" -ToSession $Session +$Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\PattiFul" +Copy-Item "D:\Folder003\" -Destination "C:\Folder003_Copy\" -ToSession $Session -Recurse ``` -The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session. +### Example 8: Copy a file to a remote computer and then rename the file + +The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the **Copy-Item** cmdlet to copy scriptingexample.ps1 from the D:\Folder004 folder to the C:\Folder004_Copy folder on the remote computer using the session information stored in the $Session variable. -As part of the copy operation, the command also changes the item name from scriptingexample.ps1 to scriptingexample_copy.ps1, so it can be attached to email messages. +The second command uses the `Copy-Item` cmdlet to copy "scriptingexample.ps1" from the "D:\Folder004" folder to the "C:\Folder004_Copy" folder on the remote computer using the session information stored in the `$Session` variable. +As part of the copy operation, the command also changes the item name from "scriptingexample.ps1" to "scriptingexample_copy.ps1", so it can be attached to email messages. This command does not delete the original file. -### Example 9: Copy a remote file to the local computer ```powershell -PS C:\> $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" -PS C:\> Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession $Session +$Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\PattiFul" +Copy-Item "D:\Folder004\scriptingexample.ps1" -Destination "C:\Folder004_Copy\scriptingexample_copy.ps1" -ToSession $Session ``` -The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session. +### Example 9: Copy a remote file to the local computer -The second command uses the **Copy-Item** cmdlet to copy test.log from the remote C:\MyRemoteData\ to the local D:\MyLocalData folder using the session information stored in the $Session variable. +The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. + +The second command uses the `Copy-Item` cmdlet to copy test.log from the remote "C:\MyRemoteData\" to the local "D:\MyLocalData" folder using the session information stored in the `$Session` variable. This command does not delete the original file. -### Example 10: Copy the entire contents of a remote folder to the local computer ```powershell -PS C:\> $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" -PS C:\> Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\" -FromSession $Session +$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" +Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession $Session ``` -The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session. +### Example 10: Copy the entire contents of a remote folder to the local computer -The second command uses the **Copy-Item** cmdlet to copy the entire contents from the remote C:\MyRemoteData\scripts folder to the local D:\MyLocalData folder using the session information stored in the $Session variable. +The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. + +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote "C:\MyRemoteData\scripts" folder to the local "D:\MyLocalData" folder using the session information stored in the `$Session` variable. If the scripts folder contains files in subfolders, those subfolders are copied with their file trees intact. -### Example 11: Recursively copy the entire contents of a remote folder to the local computer ```powershell -PS C:\> $Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" -PS C:\> Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\scripts" -FromSession $Session -Recurse +$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" +Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\" -FromSession $Session ``` -The first command creates a session to the remote computer named Server01 with the credential of Contoso\PattiFul and stores the results in the variable named $Session. +### Example 11: Recursively copy the entire contents of a remote folder to the local computer + +The first command creates a session to the remote computer named "Server01" with the credential of "Contoso\PattiFul" and stores the results in the variable named `$Session`. -The second command uses the **Copy-Item** cmdlet to copy the entire contents from the remote C:\MyRemoteData\scripts folder to the local D:\MyLocalData\scripts folder using the session information stored in the $Session variable. -Since this command uses the *Recurse* parameter, the operation creates the scripts folder if it does not already exist. If the scripts folder contains files in subfolders, those subfolders are copied with their file trees intact. +The second command uses the `Copy-Item` cmdlet to copy the entire contents from the remote "C:\MyRemoteData\scripts" folder to the local "D:\MyLocalData\scripts" folder using the session information stored in the `$Session` variable. +Since this command uses the **Recurse** parameter, the operation creates the scripts folder if it does not already exist. If the scripts folder contains files in subfolders, those subfolders are copied with their file trees intact. + +```powershell +$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\PattiFul" +Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\scripts" -FromSession $Session -Recurse +``` ## PARAMETERS ### -Container + Indicates that this cmdlet preserves container objects during the copy operation. ```yaml @@ -174,13 +189,15 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -189,12 +206,13 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Destination + Specifies the path to the new location. To rename a copied item, include the new name in the value. @@ -211,8 +229,11 @@ Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, an item or items that this cmdlet excludes from the operation. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -223,14 +244,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects, rather than have PowerShell filter the objects after they are retrieved. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -241,10 +264,11 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Indicates that this cmdlet copies items that cannot otherwise be changed, such as copying over a read-only file or alias. ```yaml @@ -260,7 +284,11 @@ Accept wildcard characters: False ``` ### -Include -Specifies, as a string array, only those items upon which the cmdlet acts, excluding all others. + +Specifies, as a string array, an item or items that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -275,8 +303,9 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies a path to the item. -The value of the *LiteralPath* parameter is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -294,6 +323,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. @@ -310,6 +340,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies, as a string array, the path to the items to copy. ```yaml @@ -325,6 +356,7 @@ Accept wildcard characters: False ``` ### -Recurse + Indicates that this cmdlet performs a recursive copy. ```yaml @@ -340,6 +372,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -355,6 +388,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -370,26 +404,8 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -FromSession + Specifies the **PSSession** object from which a remote file is being copied. When you use this parameter, the *Path* and *LiteralPath* parameters refer to the local path on the remote machine. @@ -406,6 +422,7 @@ Accept wildcard characters: False ``` ### -ToSession + Specifies the **PSSession** object to which a remote file is being copied. When you use this parameter, the *Path* and *LiteralPath* parameters refer to the local path on the remote machine. @@ -422,28 +439,30 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path to this cmdlet. ## OUTPUTS ### None or an object representing the copied item. + When you use the *PassThru* parameter, this cmdlet returns an object that represents the copied item. Otherwise, this cmdlet does not generate any output. ## NOTES -* This cmdlet is similar to the cp or copy commands in other shells. - This cmdlet is designed to work with the data exposed by any provider. +- This cmdlet is similar to the cp or copy commands in other shells. + +This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. -* - ## RELATED LINKS [Clear-Item](Clear-Item.md) @@ -463,3 +482,5 @@ For more information, see about_Providers. [Set-Item](Set-Item.md) [Get-PSProvider](Get-PSProvider.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Copy-ItemProperty.md b/reference/6/Microsoft.PowerShell.Management/Copy-ItemProperty.md index f7101085be4b..a6a0adfb245f 100644 --- a/reference/6/Microsoft.PowerShell.Management/Copy-ItemProperty.md +++ b/reference/6/Microsoft.PowerShell.Management/Copy-ItemProperty.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821575 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Copy-ItemProperty --- - # Copy-ItemProperty ## SYNOPSIS + Copies a property and value from a specified location to another location. ## SYNTAX ### Path (Default) + ``` Copy-ItemProperty [-Path] [-Name] [-Destination] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -23,6 +24,7 @@ Copy-ItemProperty [-Path] [-Name] [-Destination] [- ``` ### LiteralPath + ``` Copy-ItemProperty -LiteralPath [-Name] [-Destination] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -30,28 +32,32 @@ Copy-ItemProperty -LiteralPath [-Name] [-Destination] Copy-ItemProperty -Path "MyApplication" -Destination "HKLM:\Software\MyApplicationRev2" -Name "MyProperty" -``` -This command copies the property named MyProperty from the MyApplication registry key to the MyApplicationRev2 registry key. +This command copies the property named "MyProperty" from the "MyApplication" registry key to the "MyApplicationRev2" registry key. + +```powershell +Copy-ItemProperty -Path "MyApplication" -Destination "HKLM:\Software\MyApplicationRev2" -Name "MyProperty" +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -60,12 +66,13 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Destination + Specifies the path to the destination location. ```yaml @@ -81,8 +88,11 @@ Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, an item or items that this cmdlet excludes. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -93,14 +103,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when this cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -111,11 +123,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Forces the command to run without asking for user confirmation. +Implementation varies from provider to provider. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml Type: SwitchParameter @@ -124,13 +139,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include -Specifies, as a string array, an item or items upon which the cmdlet will act, excluding all others. + +Specifies, as a string array, an item or items that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -145,8 +164,9 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies a path to the item property. -The value of the *LiteralPath* parameter is used exactly as it is typed. + +Specifies the path to the current location of the property. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -164,6 +184,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the property to be copied. ```yaml @@ -179,6 +200,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. @@ -195,6 +217,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies, as a string array, the path to the property to be copied. ```yaml @@ -210,6 +233,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -225,6 +249,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -240,43 +265,26 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path to this cmdlet. ## OUTPUTS ### None or System.Management.Automation.PSCustomObject -When you use the *Passthru* parameter, this cmdlet generates a **PsCustomObject** representing the copied item property. + +When you use the **Passthru** parameter, this cmdlet generates a **PsCustomObject** representing the copied item property. Otherwise, this cmdlet does not generate any output. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. -* +- This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. ## RELATED LINKS @@ -292,4 +300,6 @@ Otherwise, this cmdlet does not generate any output. [Set-ItemProperty](Set-ItemProperty.md) -[Get-PSProvider](Get-PSProvider.md) \ No newline at end of file +[Get-PSProvider](Get-PSProvider.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Get-ChildItem.md b/reference/6/Microsoft.PowerShell.Management/Get-ChildItem.md index 91ad398b312e..fd2d88928ab4 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-ChildItem.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-ChildItem.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821580 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Get-ChildItem --- - # Get-ChildItem ## Synopsis @@ -43,10 +42,6 @@ A location can be a file system location, such as a directory, or a location exp ### Example 1: Get child items in the current directory -```powershell -Get-ChildItem -``` - This command gets the child items in the current location. If the location is a file system directory, it gets the files and sub-directories in the current directory. If the item does not have child items, this command returns to the command prompt without displaying anything. @@ -54,82 +49,78 @@ If the item does not have child items, this command returns to the command promp The default display lists the mode (attributes), last write time, file size (length), and the name of the file. The valid values for mode are `d` (directory), `a` (archive), `r` (read-only), `h` (hidden), and `s` (system). -### Example 2: Get all files with the specified file extension in the current directory and subdirectories - ```powershell -Get-ChildItem -Path *.txt -Recurse -Force +Get-ChildItem ``` -This command gets all of the .txt files in the current directory and its subdirectories. +### Example 2: Get all files with the specified file extension in the current directory and subdirectories + +This command gets all of the ".txt" files in the current directory and its subdirectories. The `-Recurse` parameter directs PowerShell to get objects recursively, and it indicates that the subject of the command is the specified directory and its contents. The `-Force` parameter adds hidden files to the display. -To use the `-Recurse` parameter on Windows PowerShell 2.0 and earlier versions of Windows PowerShell, the value use the `-Path` parameter must be a container. -Use the `-Include` parameter to specify the .txt file type. -For example, `Get-ChildItem -Path .\* -Include *.txt -Recurse` +```powershell +Get-ChildItem -Path *.txt -Recurse -Force +``` ### Example 3: Get all child items using an inclusion and exclusion +This command lists the ".txt" files in the "Logs" subdirectory, except for those whose names start with the letter 'A'. +It uses the wildcard character (`*`) to indicate the contents of the "Logs" subdirectory, not the directory container. +Because the command does not include the `-Recurse` parameter, `Get-ChildItem` does not include the content of directory automatically; you need to specify it. + ```powershell Get-ChildItem -Path C:\Windows\Logs\* -Include *.txt -Exclude A* ``` -This command lists the .txt files in the Logs subdirectory, except for those whose names start with the letter A. -It uses the wildcard character (`*`) to indicate the contents of the Logs subdirectory, not the directory container. -Because the command does not include the `-Recurse` parameter, `Get-ChildItem` does not include the content of directory automatically; you need to specify it. - ### Example 4: Get all registry keys in a specific key +This command gets all of the registry keys in the "HKEY_LOCAL_MACHINE\SOFTWARE" key in the registry of the local computer. + ```powershell Get-ChildItem -Path HKLM:\Software ``` -This command gets all of the registry keys in the HKEY_LOCAL_MACHINE\SOFTWARE key in the registry of the local computer. - ### Example 5: Get the name of items in the current directory +This command gets only the names of items in the current directory. + ```powershell Get-ChildItem -Name ``` -This command gets only the names of items in the current directory. - ### Example 6: Get all certificates in a certification drive that have code-signing authority -```powershell -Import-Module Microsoft.PowerShell.Security -Get-ChildItem -Path Cert:\* -Recurse -CodeSigningCert -``` +This command gets all of the certificates in the PowerShell `Cert:` drive that have code-signing authority. -This command gets all of the certificates in the PowerShell Cert: drive that have code-signing authority. +This command uses the `Get-ChildItem` cmdlet. -The first command imports the Microsoft.PowerShell.Security module into the session. -This module includes the Certificate provider that creates the Cert: drive. +- The value of the `-Path` parameter is the Cert: drive. +- The `-Recurse` parameter requests a recursive search. +- The `-CodeSigningCert` parameter is a dynamic parameter that the Certificate provider adds to the `Get-ChildItem` cmdlet. This parameter gets only certificates that have code-signing authority. -The second command uses the `Get-ChildItem` cmdlet. -The value of the `-Path` parameter is the Cert: drive. -The `-Recurse` parameter requests a recursive search. -The `-CodeSigningCert` parameter is a dynamic parameter that the Certificate provider adds to the `Get-ChildItem` cmdlet. -This parameter gets only certificates that have code-signing authority. +For more information about the Certificate provider and the `Cert:` drive, go to [Certificate Provider](../Microsoft.PowerShell.Security/Providers/about_Certificate_Provider.md) or use the `Update-Help` cmdlet to download the help files for the **Microsoft.PowerShell.Security** module and then type `Get-Help Certificate`. -For more information about the Certificate provider and the Cert: drive, go to [Certificate Provider](../microsoft.powershell.security/providers/certificate-provider.md) or use the `Update-Help` cmdlet to download the help files for the Microsoft.PowerShell.Security module and then type `Get-Help Certificate`. +```powershell +Get-ChildItem -Path Cert:\* -Recurse -CodeSigningCert +``` ### Example 7: Get all items in the specified directory and its subdirectories that have an inclusion and exclusion +This command gets all of the items in the "C:\Windows" directory and its subdirectories that have "mouse" in the file name, except for those with a ".png" file name extension. + ```powershell Get-ChildItem -Path C:\Windows -Include *mouse* -Exclude *.png ``` -This command gets all of the items in the C:\Windows directory and its subdirectories that have "mouse" in the file name, except for those with a .png file name extension. - ### Example 8: Get all items in the specified directory and its subdirectories limited by the Depth parameter +This command gets all of the items in the "C:\Windows" directory and its subdirectories up to 2 level below in depth. + ```powershell Get-ChildItem -Path C:\Windows -Depth 2 ``` -This command gets all of the items in the C:\Windows directory and its subdirectories up to 2 level below in depth. - ## Parameters ### -Attributes @@ -146,24 +137,24 @@ To find files and folders with commonly used attributes, you can use the `-Attri The `-Attributes` parameter supports the following attributes: -- Archive -- Compressed -- Device -- Directory -- Encrypted -- Hidden -- IntegrityStream -- Normal -- NoScrubData -- NotContentIndexed -- Offline -- ReadOnly -- ReparsePoint -- SparseFile -- System -- Temporary - -For a description of these attributes, see the [FileAttributes Enumeration](http://go.microsoft.com/fwlink/?LinkId=201508). +- **Archive** +- **Compressed** +- **Device** +- **Directory** +- **Encrypted** +- **Hidden** +- **IntegrityStream** +- **Normal** +- **NoScrubData** +- **NotContentIndexed** +- **Offline** +- **ReadOnly** +- **ReparsePoint** +- **SparseFile** +- **System** +- **Temporary** + +For a description of these attributes, see the [FileAttributes Enumeration](/dotnet/api/system.io.fileattributes). Use the following operators to combine attributes: @@ -180,7 +171,6 @@ You can use the following abbreviations for commonly used attributes: - `R` (Read-only) - `S` (System) - ```yaml Type: System.Management.Automation.FlagsExpression`1[System.IO.FileAttributes] Parameter Sets: (All) @@ -217,7 +207,7 @@ Gets directories (folders). To get only directories, use the `-Directory` parameter and omit the `-File` parameter. To exclude directories, use the `-File` parameter and omit the `-Directory` parameter, or use the `-Attributes` parameter. -To get directories, use the Directory parameter, its "`ad`" alias, or the Directory attribute of the `-Attributes` parameter. +To get directories, use the Directory parameter, its `ad` alias, or the Directory attribute of the `-Attributes` parameter. ```yaml Type: SwitchParameter @@ -233,10 +223,10 @@ Accept wildcard characters: False ### -Exclude -Omits the specified items. -The value of this parameter qualifies the `-Path` parameter. +Specifies, as a string array, a property or property that this cmdlet excludes from the operation. +The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". -Wildcards are permitted. +Wildcard characters are permitted. ```yaml Type: String[] @@ -256,7 +246,7 @@ Gets files. To get only files, use the `-File` parameter and omit the Directory parameter. To exclude files, use the `-Directory` parameter and omit the `-File` parameter, or use the `-Attributes` parameter. -To get files, use the File parameter, its "`af`" alias, or the File value of the `-Attributes` parameter. +To get files, use the File parameter, its `af` alias, or the File value of the `-Attributes` parameter. ```yaml Type: SwitchParameter @@ -272,10 +262,11 @@ Accept wildcard characters: False ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the `-Path` parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having PowerShell filter the objects after they are retrieved. +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -332,7 +323,7 @@ Accept wildcard characters: False Gets only hidden files and directories (folders). By default, `Get-ChildItem` gets only non-hidden items, but you can use the `-Force` parameter to include hidden items in the results. -To get only hidden items, use the `-Hidden` parameter, its "`h`" or "`ah`" aliases, or the Hidden value of the `-Attributes` parameter. To exclude hidden items, omit the `-Hidden` parameter or use the `-Attributes` parameter. +To get only hidden items, use the `-Hidden` parameter, its `h` or `ah` aliases, or the Hidden value of the `-Attributes` parameter. To exclude hidden items, omit the `-Hidden` parameter or use the `-Attributes` parameter. ```yaml Type: SwitchParameter @@ -348,10 +339,10 @@ Accept wildcard characters: False ### -Include -Gets only the specified items. -The value of this parameter qualifies the `-Path` parameter. +Specifies, as a string array, an item or items that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". -Wildcards are permitted. +Wildcard characters are permitted. The `-Include` parameter is effective only when the command includes the `-Recurse` parameter or the path leads to the contents of a directory, such as C:\Windows\*, where the "`*`" wildcard character specifies the contents of the C:\Windows directory. @@ -370,7 +361,7 @@ Accept wildcard characters: True ### -LiteralPath Specifies a path to one or more locations. -Unlike the `-Path` parameter, the value of the `-LiteralPath` parameter is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -426,7 +417,7 @@ Accept wildcard characters: True Gets only read-only files and directories (folders). -To get only read-only items, use the `-ReadOnly` parameter, its "`ar`" alias, or the ReadOnly value of the `-Attributes` parameter. To exclude read-only items, use the `-Attributes` parameter. +To get only read-only items, use the `-ReadOnly` parameter, its `ar` alias, or the ReadOnly value of the `-Attributes` parameter. To exclude read-only items, use the `-Attributes` parameter. ```yaml Type: SwitchParameter @@ -460,7 +451,7 @@ Accept wildcard characters: False Gets only system files and directories (folders). -To get only system files and folders, use the `-System` parameter, its "`as`" alias, or the System value of the `-Attributes` parameter. To exclude system files and folders, use the `-Attributes` parameter. +To get only system files and folders, use the `-System` parameter, its `as` alias, or the System value of the `-Attributes` parameter. To exclude system files and folders, use the `-Attributes` parameter. ```yaml Type: SwitchParameter @@ -496,13 +487,13 @@ If you use the `-Name` parameter, `Get-ChildItem` returns the object names as st ## Notes -You can also refer to `Get-ChildItem` by its built-in aliases, "`ls`", "`dir`", and "`gci`". For more information, see about_Aliases. +You can also refer to `Get-ChildItem` by its built-in aliases, `ls`, `dir`, and `gci`. For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). `Get-ChildItem` does not get hidden items by default. To get hidden items, use the `-Force` parameter. The `Get-ChildItem` cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type "`Get-PSProvider`". +To list the providers available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). @@ -518,4 +509,4 @@ For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/a [Get-PSProvider](Get-PSProvider.md) -[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Get-Content.md b/reference/6/Microsoft.PowerShell.Management/Get-Content.md index e83bcda02597..e0790f43a5e9 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -105,7 +105,7 @@ The manifest file contains a hash table, but if you get the contents without the ```powershell # First, use the -Path property of modules to get the path to the file that contains the module manifest for the PSScheduledJob module. # Store the path in the Manifest variable. -$Manifest = (Get-Module -List PSScheduledJob).Path +$Manifest = (Get-Module -ListAvailable PSScheduledJob).Path # Use the Invoke-Expression cmdlet to run a Get-Content command and the -Raw dynamic parameter of the Get-Content cmdlet to get the contents of the module manifest file in a single string. # Store the hashtable in the Hash variable. $Hash = Invoke-Expression (Get-Content $Manifest -Raw) @@ -116,7 +116,7 @@ $Hash ```output Name Value ---- ----- -Copyright � Microsoft Corporation. All rights reserved. +Copyright © Microsoft Corporation. All rights reserved. ModuleToProcess Microsoft.PowerShell.ScheduledJob.dll FormatsToProcess PSScheduledJob.Format.ps1xml PowerShellVersion 3.0 @@ -162,7 +162,7 @@ Accept wildcard characters: True ### -LiteralPath Specifies the path to an item. -Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. @@ -402,18 +402,19 @@ Specifies the file encoding. The default is ASCII. Valid values are: -- ASCII: Uses the encoding for the ASCII (7-bit) character set. -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. -- String: Uses the encoding type for a string. -- Unicode: Encodes in UTF-16 format using the little-endian byte order. -- UTF7: Encodes in UTF-7 format. -- UTF8: Encodes in UTF-8 format. -- UTF8BOM: Encodes in UTF-8 format with Byte Order Mark (BOM) -- UF8NOBOM: Encodes in UTF-8 format without Byte Order Mark (BOM) -- UTF32: Encodes in UTF-32 format. -- Default: Encodes in the default installed code page. -- OEM: Uses the default encoding for MS-DOS and console programs. -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. +- **ASCII**: Uses the encoding for the ASCII (7-bit) character set. +- **BigEndianUnicode**: Encodes in UTF-16 format using the big-endian byte order. +- **Default**: Encodes using the default value: ASCII. +- **OEM**: Uses the default encoding for MS-DOS and console programs. +- **Byte**: Encodes a set of characters into a sequence of bytes. +- **String**: Uses the encoding type for a string. +- **Unicode**: Encodes in UTF-16 format using the little-endian byte order. +- **UTF7**: Encodes in UTF-7 format. +- **UTF8**: Encodes in UTF-8 format. +- **UTF8BOM**: Encodes in UTF-8 format with Byte Order Mark (BOM) +- **UF8NOBOM**: Encodes in UTF-8 format without Byte Order Mark (BOM) +- **UTF32**: Encodes in UTF-32 format. +- **Unknown**: The encoding type is unknown or invalid; the data can be treated as binary. Encoding is a dynamic parameter that the FileSystem provider adds to the `Get-Content` cmdlet. This parameter works only in file system drives. @@ -477,7 +478,7 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -485,7 +486,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.Int64, System.String[], System.Management.Automation.PSCredential -You can pipe the read count, total count, paths, or credentials to Get-Content. +You can pipe the read count, total count, paths, or credentials to `Get-Content`. ## OUTPUTS diff --git a/reference/6/Microsoft.PowerShell.Management/Get-Item.md b/reference/6/Microsoft.PowerShell.Management/Get-Item.md index 402cae67e238..6afbe256eb4d 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,38 +7,47 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821587 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Get-Item --- - # Get-Item ## SYNOPSIS + Gets the item at the specified location. ## SYNTAX ### Path (Default) + ``` Get-Item [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-UseTransaction] [-Stream ] [] ``` ### LiteralPath + ``` Get-Item -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-UseTransaction] [-Stream ] [] ``` ## DESCRIPTION -The **Get-Item** cmdlet gets the item at the specified location. -It does not get the contents of the item at the location unless you use a wildcard character (*) to request all the contents of the item. + +The `Get-Item` cmdlet gets the item at the specified location. +It does not get the contents of the item at the location unless you use a wildcard character ('*') to request all the contents of the item. This cmdlet is used by PowerShell providers to navigate through different types of data stores. ## EXAMPLES ### Example 1: Get the current directory + +This command gets the current directory. +The dot ('.') represents the item at the current location (not its contents). + +```powershell +Get-Item . ``` -PS C:\> Get-Item . +```output Directory: C:\ Mode LastWriteTime Length Name @@ -46,13 +55,16 @@ Mode LastWriteTime Length Name d---- 7/26/2006 10:01 AM ps-test ``` -This command gets the current directory. -The dot (.) represents the item at the current location (not its contents). - ### Example 2: Get all the items in the current directory + +This command gets all the items in the current directory. +The wildcard character ('*') represents all the contents of the current item. + +```powershell +Get-Item * ``` -PS C:\> Get-Item * +```output Directory: C:\ps-test Mode LastWriteTime Length Name @@ -65,56 +77,59 @@ d---- 7/26/2006 9:26 AM Recs -a--- 7/14/2006 10:47 AM 30 test.txt ``` -This command gets all the items in the current directory. -The wildcard character (*) represents all the contents of the current item. - ### Example 3: Get the current directory of a drive -``` -PS C:\> Get-Item C:\ -``` This command gets the current directory of the C: drive. The object that is retrieved represents only the directory, not its contents. -### Example 4: Get items in the specified drive -``` -PS C:\> Get-Item C:\* +```powershell +Get-Item C:\ ``` +### Example 4: Get items in the specified drive + This command gets the items in the C: drive. -The wildcard character (*) represents all the items in the container, not just the container. +The wildcard character ('*') represents all the items in the container, not just the container. -In PowerShell, use a single asterisk (*) to get contents, instead of the traditional *.*. -The format is interpreted literally, so *.* would not retrieve directories or file names without a dot. +In PowerShell, use a single asterisk ('*') to get contents, instead of the traditional "*.*". +The format is interpreted literally, so "*.*" would not retrieve directories or file names without a dot. -### Example 5: Get a property in the specified directory -``` -PS C:\> (Get-Item C:\Windows).LastAccessTime +```powershell +Get-Item C:\* ``` -This command gets the LastAccessTime property of the C:\Windows directory. -LastAccessTime is just one property of file system directories. +### Example 5: Get a property in the specified directory + +This command gets the **LastAccessTime** property of the "C:\Windows" directory. +**LastAccessTime** is just one property of file system directories. To see all of the properties of a directory, type `(Get-Item \) | Get-Member`. -### Example 6: Show the contents of a registry key -``` -PS C:\> Get-Item hklm:\software\microsoft\powershell\1\shellids\microsoft.powershell\* +```powershell +(Get-Item C:\Windows).LastAccessTime ``` -This command shows the contents of the Microsoft.PowerShell registry key. -You can use this cmdlet with the PowerShell Registry provider to get registry keys and subkeys, but you must use the **Get-ItemProperty** cmdlet to get the registry values and data. +### Example 6: Show the contents of a registry key -### Example 7: Get items in a directory that have an exclusion -``` -PS C:\> Get-Item c:\Windows\*.* -exclude "w*" +This command shows the contents of the **Microsoft.PowerShell** registry key. +You can use this cmdlet with the PowerShell Registry provider to get registry keys and subkeys, but you must use the `Get-ItemProperty` cmdlet to get the registry values and data. + +```powershell +Get-Item HKLM:\Software\Microsoft\Powershell\1\Shellids\Microsoft.Powershell\ ``` -This command gets items in the Windows directory with names that include a dot (.), but do not begin with w*. -This command works only when the path includes a wildcard character (*) to specify the contents of the item. +### Example 7: Get items in a directory that have an exclusion + +This command gets items in the Windows directory with names that include a dot ('.'), but do not begin with "w*". +This command works only when the path includes a wildcard character ('*') to specify the contents of the item. + +```powershell +Get-Item c:\Windows\*.* -Exclude "w*" +``` ## PARAMETERS ### -Stream + This parameter is not supported by any providers installed with PowerShell. ```yaml @@ -130,13 +145,15 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user-name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -151,12 +168,13 @@ Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, an item or items that this cmdlet excludes in the operation. -The value of this parameter qualifies the Path parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. -The *Exclude* parameter is effective only when the command includes the contents of an item, such as C:\Windows\*, where the wildcard character specifies the contents of the C:\Windows directory. +The **Exclude** parameter is effective only when the command includes the contents of an item, such as "C:\Windows\*", where the wildcard character specifies the contents of the "C:\Windows" directory. ```yaml Type: String[] @@ -171,10 +189,12 @@ Accept wildcard characters: False ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when this cmdlet gets the objects, rather than having PowerShell filter the objects after they are retrieved. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -185,14 +205,15 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Indicates that this cmdlet gets items that cannot otherwise be accessed, such as hidden items. Implementation varies from provider to provider. -For more information, see about_Providers. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +Even using the **Force** parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter @@ -207,12 +228,13 @@ Accept wildcard characters: False ``` ### -Include + Specifies, as a string array, an item or items that this cmdlet includes in the operation. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. -The *Include* parameter is effective only when the command includes the contents of an item, such as C:\Windows\*, where the wildcard character specifies the contents of the C:\Windows directory. +The **Include** parameter is effective only when the command includes the contents of an item, such as "C:\Windows\*", where the wildcard character specifies the contents of the "C:\Windows" directory. ```yaml Type: String[] @@ -223,12 +245,13 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath + Specifies a path to the item. -Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -246,13 +269,14 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to an item. This cmdlet gets the item at the specified location. Wildcards are permitted. This parameter is required, but the parameter name ("Path") is optional. -Use a dot (.) to specify the current location. -Use the wildcard character (*) to specify all the items in the current location. +Use a dot ('.') to specify the current location. +Use the wildcard character ('*') to specify all the items in the current location. ```yaml Type: String[] @@ -266,51 +290,34 @@ Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path to this cmdlet. ## OUTPUTS ### System.Object + This cmdlet returns the objects that it gets. The type is determined by the type of objects in the path. ## NOTES -* You can also refer to this cmdlet by its built-in alias, "gi". For more information, see about_Aliases. - This cmdlet does not have a *Recurse* parameter, because it gets only an item, not its contents. -To get the contents of an item recursively, use Get-ChildItem. +This cmdlet does not have a **Recurse** parameter, because it gets only an item, not its contents. +To get the contents of an item recursively, use `Get-ChildItem`. - To navigate through the registry, use this cmdlet to get registry keys and the Get-ItemProperty to get registry values and data. +To navigate through the registry, use this cmdlet to get registry keys and the `Get-ItemProperty` to get registry values and data. The registry values are considered to be properties of the registry key. - This cmdlet is designed to work with the data exposed by any provider. +This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS @@ -334,4 +341,6 @@ For more information, see about_Providers. [Get-ItemProperty](Get-ItemProperty.md) -[Get-PSProvider](Get-PSProvider.md) \ No newline at end of file +[Get-PSProvider](Get-PSProvider.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Get-ItemProperty.md b/reference/6/Microsoft.PowerShell.Management/Get-ItemProperty.md index 8edadcf960fc..7ddb4808a500 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-ItemProperty.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-ItemProperty.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,80 +7,87 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821588 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Get-ItemProperty --- - # Get-ItemProperty ## SYNOPSIS + Gets the properties of a specified item. ## SYNTAX ### Path (Default) + ``` Get-ItemProperty [-Path] [[-Name] ] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-UseTransaction] [] ``` ### LiteralPath + ``` Get-ItemProperty -LiteralPath [[-Name] ] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-UseTransaction] [] ``` ## DESCRIPTION -The **Get-ItemProperty** cmdlet gets the properties of the specified items. + +The `Get-ItemProperty` cmdlet gets the properties of the specified items. For example, you can use this cmdlet to get the value of the LastAccessTime property of a file object. You can also use this cmdlet to view registry entries and their values. ## EXAMPLES ### Example 1: Get information about a specific directory -``` -PS C:\> Get-ItemProperty C:\Windows -``` -This command gets information about the C:\Windows directory. +This command gets information about the "C:\Windows" directory. -### Example 2: Get the properties of a specific file -``` -PS C:\> Get-ItemProperty C:\Test\Weather.xls | Format-List +```powershell +Get-ItemProperty C:\Windows ``` -This command gets the properties of the C:\Test\Weather.xls file. -The result is piped to the Format-List cmdlet to display the output as a list. +### Example 2: Get the properties of a specific file -### Example 3: Display the value name and data of registry entries in a registry subkey -``` -PS C:\> Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion +This command gets the properties of the "C:\Test\Weather.xls" file. +The result is piped to the `Format-List` cmdlet to display the output as a list. + +```powershell +Get-ItemProperty C:\Test\Weather.xls | Format-List ``` -This command displays the value name and data of each of the registry entries contained in the CurrentVersion registry subkey. -Note that the command requires that there is a PowerShell drive named HKLM: that is mapped to the HKEY_LOCAL_MACHINE hive of the registry. +### Example 3: Display the value name and data of registry entries in a registry subkey + +This command displays the value name and data of each of the registry entries contained in the "CurrentVersion" registry subkey. +Note that the command requires that there is a PowerShell drive named `HKLM:` that is mapped to the "HKEY_LOCAL_MACHINE" hive of the registry. A drive with that name and mapping is available in PowerShell by default. Alternatively, the path to this registry subkey can be specified by using the following alternative path that begins with the provider name followed by two colons: -Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion. +"Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion". -### Example 4: Get the value name and data of a registry entry in a registry subkey -``` -PS C:\> Get-ItemProperty -path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion -name "ProgramFilesDir" +```powershell +Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion ``` -This command gets the value name and data of the ProgramFilesDir registry entry in the CurrentVersion registry subkey. -The command uses the *Path* parameter to specify the subkey and the Name parameter to specify the value name of the entry. +### Example 4: Get the value name and data of a registry entry in a registry subkey + +This command gets the value name and data of the "ProgramFilesDir" registry entry in the "CurrentVersion" registry subkey. +The command uses the **Path** parameter to specify the subkey and the Name parameter to specify the value name of the entry. The command uses a back tick or grave accent (\`), the PowerShell continuation character, to continue the command on the second line. -### Example 5: Get the value names and data of registry entries in a registry key +```powershell +Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion -Name "ProgramFilesDir" ``` -PS C:\> Get-ItemProperty -path HKLM:\SOFTWARE\Microsoft\PowerShell\1\PowerShellEngine - - - +### Example 5: Get the value names and data of registry entries in a registry key +This command gets the value names and data of the registry entries in the "PowerShellEngine" registry key. +The results are shown in the following sample output. +```powershell +Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\PowerShellEngine +``` +```output ApplicationBase : C:\Windows\system32\WindowsPowerShell\v1.0\ ConsoleHostAssemblyName : Microsoft.PowerShell.ConsoleHost, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, ProcessorArchitecture=msil PowerShellVersion : 2.0 @@ -89,19 +96,40 @@ CTPVersion : 5 PSCompatibleVersion : 1.0,2.0 ``` -This command gets the value names and data of the registry entries in the PowerShellEngine registry key. +### Example 6: Get, format, and display the results of registry values and data + +This example shows how to format the output of a `Get-ItemProperty` command in a list to make it easy to see the registry values and data and to make it easy to interpret the results. + +The first command uses the `Get-ItemProperty` cmdlet to get the registry entries in the **Microsoft.PowerShell** subkey. +This subkey stores options for the default shell for PowerShell. The results are shown in the following sample output. -### Example 6: Get, format, and display the results of registry values and data +The output shows that there are two registry entries, "Path" and "ExecutionPolicy". +When a registry key contains fewer than five entries, by default it is displayed in a table, but it is often easier to view in a list. + +The second command uses the same `Get-ItemProperty` command. +However, this time, the command uses a pipeline operator (`|`) to send the results of the command to the `Format-List` cmdlet. +The `Format-List` command uses the Property parameter with a value of '*' (all) to display all of the properties of the objects in a list. +The results are shown in the following sample output. + +The resulting display shows the "Path" and "ExecutionPolicy" registry entries, along with several less familiar properties of the registry key object. +The other properties, prefixed with PS, are properties of PowerShell custom objects, such as the objects that represent the registry keys. + +```powershell +Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell ``` -PS C:\> Get-ItemProperty -path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell +```output Path ExecutionPolicy ---- --------------- C:\Windows\system32\WindowsPowerShell\v1.0\powershell.exe RemoteSigned +``` -PS C:\> Get-ItemProperty -path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell | Format-List -property * +```powershell +Get-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell | Format-List -Property * +``` +```output PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\Software\Microsoft\PowerShell\1\ShellIds\Micro soft.PowerShell PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\Software\Microsoft\PowerShell\1\ShellIds @@ -112,33 +140,18 @@ Path : C:\Windows\system32\WindowsPowerShell\v1.0\powershell.exe ExecutionPolicy : RemoteSigned ``` -This example shows how to format the output of a **Get-ItemProperty** command in a list to make it easy to see the registry values and data and to make it easy to interpret the results. - -The first command uses the **Get-ItemProperty** cmdlet to get the registry entries in the Microsoft.PowerShell subkey. -This subkey stores options for the default shell for PowerShell. -The results are shown in the following sample output. - -The output shows that there are two registry entries, Path and ExecutionPolicy. -When a registry key contains fewer than five entries, by default it is displayed in a table, but it is often easier to view in a list. - -The second command uses the same **Get-ItemProperty** command. -However, this time, the command uses a pipeline operator (|) to send the results of the command to the **Format-List** cmdlet. -The **Format-List** command uses the Property parameter with a value of * (all) to display all of the properties of the objects in a list. -The results are shown in the following sample output. - -The resulting display shows the Path and ExecutionPolicy registry entries, along with several less familiar properties of the registry key object. -The other properties, prefixed with PS, are properties of PowerShell custom objects, such as the objects that represent the registry keys. - ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -147,14 +160,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, an item or items that this cmdlet excludes from the operation. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -169,10 +185,12 @@ Accept wildcard characters: False ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when this cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -183,11 +201,15 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Include + Specifies, as a string array, an item or items that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -202,8 +224,9 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies a path to the item property. -The value of *LiteralPath* is used exactly as it is typed. + +Specifies the path to the current location of the property. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -221,6 +244,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the property or properties to retrieve. ```yaml @@ -236,6 +260,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to the item or items. ```yaml @@ -251,6 +276,7 @@ Accept wildcard characters: False ``` ### -UseTransaction + Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see Includes the command in the active transaction. @@ -270,24 +296,26 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String -You can pipe a string that contains a path to Get-ItemProperty. + +You can pipe a string that contains a path to `Get-ItemProperty`. ## OUTPUTS ### System.Boolean, System.String, System.DateTime + Get-ItemProperty returns an object for each item property that it gets. The object type depends on the object that is retrieved. For example, in a file system drive, it might return a file or folder. ## NOTES -* The Get-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PSProvider". For more information, see about_Providers. -* +- The `Get-ItemProperty` cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "`Get-PSProvider`". For more information, see about_Providers. ## RELATED LINKS @@ -303,4 +331,6 @@ For example, in a file system drive, it might return a file or folder. [Rename-ItemProperty](Rename-ItemProperty.md) -[Set-ItemProperty](Set-ItemProperty.md) \ No newline at end of file +[Set-ItemProperty](Set-ItemProperty.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Get-ItemPropertyValue.md b/reference/6/Microsoft.PowerShell.Management/Get-ItemPropertyValue.md index ca0fe058671d..de74d447747d 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-ItemPropertyValue.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-ItemPropertyValue.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,51 +7,68 @@ online version: http://go.microsoft.com/fwlink/?LinkID=389281 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Get-ItemPropertyValue --- - # Get-ItemPropertyValue ## SYNOPSIS + Gets the value for one or more properties of a specified item. ## SYNTAX ### Path (Default) + ``` Get-ItemPropertyValue [[-Path] ] [-Name] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-UseTransaction] [] ``` ### LiteralPath + ``` Get-ItemPropertyValue -LiteralPath [-Name] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-UseTransaction] [] ``` ## DESCRIPTION -The **Get-ItemPropertyValue** gets the current value for a property that you specify when you use the *Name* parameter, located in a path that you specify with either the *Path* or *LiteralPath* parameters. + +The `Get-ItemPropertyValue` gets the current value for a property that you specify when you use the *Name* parameter, located in a path that you specify with either the *Path* or *LiteralPath* parameters. ## EXAMPLES ### Example 1: Get the value of the ProductID property + +This command gets the value of the **ProductID** property of the "\SOFTWARE\Microsoft\Windows NT\CurrentVersion" object in the Windows Registry provider. + +```powershell +Get-ItemPropertyValue HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion -Name ProductID ``` -PS C:\> Get-ItemPropertyValue HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion -Name ProductID + +```output 94253-50000-11141-AA785 ``` -This command gets the value of the ProductID property of the \SOFTWARE\Microsoft\Windows NT\CurrentVersion object in the Windows Registry provider. - ### Example 2: Get the last write time of a file or folder + +This command gets the value of the **LastWriteTime** property, or the last time a file or folder was changed, from the "C:\Users\Test\Documents\ModuleToAssembly" folder, working in the FileSystem provider. + +```powershell +Get-ItemPropertyValue -Path C:\Users\Test\Documents\ModuleToAssembly -Name LastWriteTime ``` -PS C:\> Get-ItemPropertyValue -Path C:\Users\Test\Documents\ModuleToAssembly -Name LastWriteTime + +```output Wednesday, September 3, 2014 2:53:22 PM ``` -This command gets the value of the LastWriteTime property, or the last time a file or folder was changed, from the C:\Users\Test\Documents\ModuleToAssembly folder, working in the FileSystem provider. - ### Example 3: Get multiple property values of a file or folder + +This command gets the values of the **LastWriteTime**, **CreationTime**, and **Root** properties of a folder. +The property values are returned in the order in which you specified the property names. + +```powershell +Get-ItemPropertyValue -Path C:\Users\Test\Documents\ModuleToAssembly -Name LastWriteTime,CreationTime,Root ``` -PS C:\> Get-ItemPropertyValue -Path C:\Users\Test\Documents\ModuleToAssembly -Name LastWriteTime,CreationTime,Root +```output Wednesday, September 3, 2014 2:53:22 PM Wednesday, September 3, 2014 2:53:10 PM @@ -74,17 +91,18 @@ LinkType : Mode : d--hs- ``` -This command gets the values of the **LastWriteTime**, **CreationTime**, and **Root** properties of a folder. -The property values are returned in the order in which you specified the property names. - ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. + +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, you are prompted for a password. -This parameter is not supported by any providers that are installed with PowerShell. + +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -99,7 +117,11 @@ Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, an item or items that this cmdlet excludes from the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -110,12 +132,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + The syntax of the filter, including the use of wildcard characters, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. @@ -128,11 +152,15 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Include + Specifies, as a string array, an item or items that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -143,14 +171,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath -Specifies a path to the item property. -In contrast to the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. + +Specifies the path to the current location of the property. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -165,6 +195,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the property or properties to retrieve. ```yaml @@ -180,6 +211,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to the item or items. ```yaml @@ -194,42 +226,27 @@ Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path to this cmdlet. ## OUTPUTS ### System.Boolean, System.String, System.DateTime + This cmdlet returns an object for each item property value that it gets. The object type depends on the property value that is retrieved. For example, in a file system drive, the cmdlet might return a file or folder. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, run the Get-PSProvider cmdlet. For more information, see about_Providers. + +- This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, run the `Get-PSProvider` cmdlet. For more information, see about_Providers. ## RELATED LINKS @@ -239,6 +256,8 @@ For example, in a file system drive, the cmdlet might return a file or folder. [Copy-ItemProperty](Copy-ItemProperty.md) +[Get-PSProvider](Get-PSProvider.md) + [Move-ItemProperty](Move-ItemProperty.md) [New-ItemProperty](New-ItemProperty.md) @@ -249,4 +268,4 @@ For example, in a file system drive, the cmdlet might return a file or folder. [Set-ItemProperty](Set-ItemProperty.md) -[Get-PSProvider](Get-PSProvider.md) \ No newline at end of file +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Invoke-Item.md b/reference/6/Microsoft.PowerShell.Management/Invoke-Item.md index 9d0a3f4bb347..b840a75d08d9 100644 --- a/reference/6/Microsoft.PowerShell.Management/Invoke-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Invoke-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,60 +7,67 @@ online version: http://go.microsoft.com/fwlink/?LinkId=822243 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Invoke-Item --- - # Invoke-Item ## SYNOPSIS + Performs the default action on the specified item. ## SYNTAX ### Path (Default) + ``` Invoke-Item [-Path] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ### LiteralPath + ``` Invoke-Item -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ## DESCRIPTION -The **Invoke-Item** cmdlet performs the default action on the specified item. + +The `Invoke-Item` cmdlet performs the default action on the specified item. For example, it runs an executable file or opens a document file in the application associated with the document file type. The default action depends on the type of item and is determined by the PowerShell provider that provides access to the data. ## EXAMPLES ### Example 1: Open a file -``` -PS C:\> Invoke-Item "C:\Test\aliasApr04.doc" -``` -This command opens the file aliasApr04.doc in Microsoft Office Word. -In this case, opening in Word is the default action for .doc files. +This command opens the file "aliasApr04.doc" in Microsoft Office Word. +In this case, opening in Word is the default action for ".doc" files. -### Example 2: Open all files of a specific type -``` -PS C:\> Invoke-Item "C:\Documents and Settings\Lister\My Documents\*.xls" +```powershell +Invoke-Item "C:\Test\aliasApr04.doc" ``` -This command opens all of the Microsoft Office Excel spreadsheets in the C:\Documents and Settings\Lister\My Documents folder. +### Example 2: Open all files of a specific type + +This command opens all of the Microsoft Office Excel spreadsheets in the "C:\Documents and Settings\Lister\My Documents" folder. Each spreadsheet is opened in a new instance of Excel. -In this case, opening in Excel is the default action for .xls files. +In this case, opening in Excel is the default action for ".xls" files. + +```powershell +Invoke-Item "C:\Documents and Settings\Lister\My Documents\*.xls" +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -69,16 +76,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, an item or items that this cmdlet excludes from the operation. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -89,14 +97,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having PowerShell filter the objects after they are retrieved. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -107,14 +117,15 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Include + Specifies, as a string array, an item or items that this cmdlet includes in the operation. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -129,8 +140,9 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies a path to the item. -Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -148,6 +160,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to the selected item. ```yaml @@ -163,6 +176,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -178,6 +192,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -193,43 +208,26 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path to this cmdlet. ## OUTPUTS ### None + The command does not generate any output. However, output might be generated by the item that it invokes. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. -* +- This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. ## RELATED LINKS @@ -247,4 +245,6 @@ However, output might be generated by the item that it invokes. [Rename-Item](Rename-Item.md) -[Set-Item](Set-Item.md) \ No newline at end of file +[Set-Item](Set-Item.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Move-Item.md b/reference/6/Microsoft.PowerShell.Management/Move-Item.md index 7b7d36b6f2ae..e96235eae8ce 100644 --- a/reference/6/Microsoft.PowerShell.Management/Move-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Move-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,28 +7,31 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821601 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Move-Item --- - # Move-Item ## SYNOPSIS + Moves an item from one location to another. ## SYNTAX ### Path (Default) + ``` Move-Item [-Path] [[-Destination] ] [-Force] [-Filter ] [-Include ] [-Exclude ] [-PassThru] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ### LiteralPath + ``` Move-Item -LiteralPath [[-Destination] ] [-Force] [-Filter ] [-Include ] [-Exclude ] [-PassThru] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ## DESCRIPTION -The **Move-Item** cmdlet moves an item, including its properties, contents, and child items, from one location to another location. + +The `Move-Item` cmdlet moves an item, including its properties, contents, and child items, from one location to another location. The locations must be supported by the same provider. For example, it can move a file or subdirectory from one directory to another or move a registry subkey from one key to another. When you move an item, it is added to the new location and deleted from its original location. @@ -36,83 +39,91 @@ When you move an item, it is added to the new location and deleted from its orig ## EXAMPLES ### Example 1: Move a file to another directory and rename it -``` -PS C:\> Move-Item -Path C:\test.txt -Destination E:\Temp\tst.txt -``` -This command moves the Test.txt file from the C: drive to the E:\Temp directory and renames it from test.txt to tst.txt. +This command moves the "Test.txt" file from the `C:` drive to the "E:\Temp" directory and renames it from "test.txt" to "tst.txt". -### Example 2: Move a directory and its contents to another directory -``` -PS C:\> Move-Item -Path C:\Temp -Destination C:\Logs +```powershell +Move-Item -Path C:\test.txt -Destination E:\Temp\tst.txt ``` -This command moves the C:\Temp directory and its contents to the C:\Logs directory. -The Temp directory, and all of its subdirectories and files, then appear in the Logs directory. +### Example 2: Move a directory and its contents to another directory -### Example 3: Move all files of a specified extension from the current directory to another directory -``` -PS C:\> Move-Item -Path .\*.txt -Destination C:\Logs +This command moves the "C:\Temp" directory and its contents to the "C:\Logs" directory. +The "Temp" directory, and all of its subdirectories and files, then appear in the "Logs" directory. + +```powershell +Move-Item -Path C:\Temp -Destination C:\Logs ``` -This command moves all of the text files (*.txt) in the current directory (represented by a dot (.)) to the C:\Logs directory. +### Example 3: Move all files of a specified extension from the current directory to another directory -### Example 4: Recursively move all files of a specified extension from the current directory to another directory -``` -PS C:\> Get-ChildItem -Path ".\*.txt" -Recurse | Move-Item -Destination "C:\TextFiles" +This command moves all of the text files ("*.txt") in the current directory (represented by a dot ('.')) to the "C:\Logs" directory. + +```powershell +Move-Item -Path .\*.txt -Destination C:\Logs ``` -This command moves all of the text files from the current directory and all subdirectories, recursively, to the C:\TextFiles directory. +### Example 4: Recursively move all files of a specified extension from the current directory to another directory + +This command moves all of the text files from the current directory and all subdirectories, recursively, to the "C:\TextFiles" directory. -The command uses the **Get-ChildItem** cmdlet to get all of the child items in the current directory (represented by the dot \[.\]) and its subdirectories that have a *.txt file name extension. -It uses the *Recurse* parameter to make the retrieval recursive and the Include parameter to limit the retrieval to *.txt files. +The command uses the `Get-ChildItem` cmdlet to get all of the child items in the current directory (represented by the dot \[.\]) and its subdirectories that have a "*.txt" file name extension. +It uses the **Recurse** parameter to make the retrieval recursive and the Include parameter to limit the retrieval to "*.txt" files. -The pipeline operator (|) sends the results of this command to **Move-Item**, which moves the text files to the TextFiles directory. +The pipeline operator (`|`) sends the results of this command to `Move-Item`, which moves the text files to the "TextFiles" directory. -If files that are to be moved to C:\Textfiles have the same name, **Move-Item** displays an error and continues, but it moves only one file with each name to C:\Textfiles. +If files that are to be moved to "C:\Textfiles" have the same name, `Move-Item` displays an error and continues, but it moves only one file with each name to "C:\Textfiles". The other files remain in their original directories. -If the Textfiles directory (or any other element of the destination path) does not exist, the command fails. -The missing directory is not created for you, even if you use the *Force* parameter. -**Move-Item** moves the first item to a file called Textfiles and then displays an error explaining that the file already exists. +If the "Textfiles" directory (or any other element of the destination path) does not exist, the command fails. +The missing directory is not created for you, even if you use the **Force** parameter. +`Move-Item` moves the first item to a file called "Textfiles" and then displays an error explaining that the file already exists. -Also, by default, Get-ChildItem does not move hidden files. -To move hidden files, use the*Force* parameter with **Get-ChildItem**. +Also, by default, `Get-ChildItem` does not move hidden files. +To move hidden files, use the **Force** parameter with `Get-ChildItem`. -Note: In Windows PowerShell 2.0, when using the **Recurse** parameter of the **Get-ChildItem** cmdlet, the value of the **Path** parameter must be a container. +Note: In Windows PowerShell 2.0, when using the **Recurse** parameter of the `Get-ChildItem` cmdlet, the value of the **Path** parameter must be a container. Use the **Include** parameter to specify the .txt file name extension filter (`Get-ChildItem -Path .\* -Include *.txt -Recurse | Move-Item -Destination C:\TextFiles`). -### Example 5: Move registry keys and values to another key -``` -PS C:\> Move-Item "HKLM:\software\mycompany\*" "HKLM:\software\mynewcompany" +```powershell +Get-ChildItem -Path ".\*.txt" -Recurse | Move-Item -Destination "C:\TextFiles" ``` -This command moves the registry keys and values within the MyCompany registry key in HKLM\Software to the MyNewCompany key. -The wildcard character (*) indicates that the contents of the MyCompany key should be moved, not the key itself. -In this command, the optional *Path* and *Destination* parameter names are omitted. +### Example 5: Move registry keys and values to another key -### Example 6: Move a directory and its contents to a subdirectory of the specified directory -``` -PS C:\> Move-Item -LiteralPath 'Logs[Sept`06]' -Destination 'Logs[2006]' +This command moves the registry keys and values within the "MyCompany" registry key in "HKLM\Software" to the "MyNewCompany" key. +The wildcard character ('*') indicates that the contents of the "MyCompany" key should be moved, not the key itself. +In this command, the optional **Path** and **Destination** parameter names are omitted. + +```powershell +Move-Item "HKLM:\software\mycompany\*" "HKLM:\software\mynewcompany" ``` -This command moves the Logs\[Sept\`06\] directory (and its contents) into the Logs\[2006\] directory. +### Example 6: Move a directory and its contents to a subdirectory of the specified directory + +This command moves the "Logs\[Sept\`06\]" directory (and its contents) into the "Logs\[2006\]" directory. -The *LiteralPath* parameter is used instead of *Path*, because the original directory name includes left bracket and right bracket characters ("\[" and "\]"). +The **LiteralPath** parameter is used instead of **Path**, because the original directory name includes left bracket and right bracket characters ("\[" and "\]"). The path is also enclosed in single quotation marks (' '), so that the backtick symbol (\`) is not misinterpreted. -The *Destination* parameter does not require a literal path, because the Destination variable also must be enclosed in single quotation marks, because it includes brackets that can be misinterpreted. +The **Destination** parameter does not require a literal path, because the Destination variable also must be enclosed in single quotation marks, because it includes brackets that can be misinterpreted. + +```powershell +Move-Item -LiteralPath 'Logs[Sept`06]' -Destination 'Logs[2006]' +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -121,12 +132,13 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Destination + Specifies the path to the location where the items are being moved. The default is the current directory. Wildcards are permitted, but the result must specify a single location. @@ -146,10 +158,11 @@ Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, an item or items that this cmdlet excludes from the operation. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -160,14 +173,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects, rather than having PowerShell filter the objects after they are retrieved. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -178,11 +193,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Forces the command to run without asking for user confirmation. +Implementation varies from provider to provider. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml Type: SwitchParameter @@ -191,16 +209,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include + Specifies, as a string array, an item or items that this cmdlet moves in the operation. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -215,8 +234,9 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies the path to the current location of the items. -Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -234,6 +254,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. @@ -250,6 +271,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to the current location of the items. The default is the current directory. Wildcards are permitted. @@ -267,6 +289,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -282,6 +305,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -297,53 +321,36 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path to this cmdlet. ## OUTPUTS ### None or an object representing the moved item. + When you use the *PassThru* parameter, this cmdlet generates an object representing the moved item. Otherwise, this cmdlet does not generate any output. ## NOTES -* This cmdlet will move files between drives that are supported by the same provider, but it will move directories only within the same drive. - Because a **Move-Item** command moves the properties, contents, and child items of an item, all moves are recursive by default. +- This cmdlet will move files between drives that are supported by the same provider, but it will move directories only within the same drive. + +Because a `Move-Item` command moves the properties, contents, and child items of an item, all moves are recursive by default. - You can also refer to this cmdlet by its built-in aliases, "move", "mv", and "mi". +You can also refer to this cmdlet by its built-in aliases, "move", "mv", and "mi". For more information, see about_Aliases. - This cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type Get-PSProvider. +This cmdlet is designed to work with the data exposed by any provider. +To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. -* - ## RELATED LINKS [Clear-Item](Clear-Item.md) @@ -362,4 +369,6 @@ For more information, see about_Providers. [Set-Item](Set-Item.md) -[Get-PSProvider](Get-PSProvider.md) \ No newline at end of file +[Get-PSProvider](Get-PSProvider.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Move-ItemProperty.md b/reference/6/Microsoft.PowerShell.Management/Move-ItemProperty.md index 2a694af19e28..99e6d4ad3cff 100644 --- a/reference/6/Microsoft.PowerShell.Management/Move-ItemProperty.md +++ b/reference/6/Microsoft.PowerShell.Management/Move-ItemProperty.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821602 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Move-ItemProperty --- - # Move-ItemProperty -## SYNOPSIS +## Synopsis + Moves a property from one location to another. ## SYNTAX ### Path (Default) + ``` Move-ItemProperty [-Path] [-Name] [-Destination] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -23,36 +24,41 @@ Move-ItemProperty [-Path] [-Name] [-Destination] ``` ### LiteralPath + ``` Move-ItemProperty -LiteralPath [-Name] [-Destination] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` -## DESCRIPTION -The **Move-ItemProperty** cmdlet moves a property of an item from one item to another item. +## Description + +The `Move-ItemProperty` cmdlet moves a property of an item from one item to another item. For instance, it can move a registry entry from one registry key to another registry key. When you move an item property, it is added to the new location and deleted from its original location. ## EXAMPLES ### Example 1: Move a registry value and its data to another key -``` -PS C:\> Move-ItemProperty "HKLM:\Software\MyCompany\MyApp" -Name "Version" -Destination "HKLM:\Software\MyCompany\NewApp" -``` -This command moves the Version registry value, and its data, from the MyApp subkey to the NewApp subkey of the HKLM\Software\MyCompany registry key. +This command moves the Version registry value, and its data, from the "MyApp" subkey to the NewApp subkey of the "HKLM\Software\MyCompany" registry key. + +```powershell +Move-ItemProperty "HKLM:\Software\MyCompany\MyApp" -Name "Version" -Destination "HKLM:\Software\MyCompany\NewApp" +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -61,12 +67,13 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Destination + Specifies the path to the destination location. ```yaml @@ -82,10 +89,11 @@ Accept wildcard characters: False ``` ### -Exclude + Specifies, as a string array, a property or property that this cmdlet excludes from the operation. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -96,14 +104,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when this cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. + +Specifies a filter in the format or language of the provider. +The value of this parameter qualifies the **Path** parameter. + +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -114,11 +124,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Forces the command to run without asking for user confirmation. +Implementation varies from provider to provider. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml Type: SwitchParameter @@ -127,16 +140,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include -Specifies, as a string array, a property or property that this cmdlet moves in the operation. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcards are permitted. + +Specifies, as a string array, a property or property that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -147,12 +161,13 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath + Specifies the path to the current location of the property. -Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -170,6 +185,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the property to be moved. ```yaml @@ -185,6 +201,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. @@ -201,6 +218,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to the current location of the property. Wildcards are permitted. @@ -217,6 +235,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -232,6 +251,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -247,50 +267,30 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path to this cmdlet. ## OUTPUTS ### None or System.Management.Automation.PSCustomObject -When you use the *PassThru* parameter, this cmdlet generates a **PSCustomObject** representing the moved item property. + +When you use the **PassThru** parameter, this cmdlet generates a **PSCustomObject** representing the moved item property. Otherwise, this cmdlet does not generate any output. ## NOTES -* The names of the *Path*, *Destination*, and *Name* parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Path, Destination, and Name. If you include the parameter names, the parameters can appear in any order. - You can also refer to this cmdlet by its built-in alias, "mp". -For more information, see about_Aliases. +- The names of the **Path**, **Destination**, and **Name** parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Path, Destination, and Name. If you include the parameter names, the parameters can appear in any order. - This cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type `Get-PSProvider`. -For more information, see about_Providers. +- You can also refer to this cmdlet by its built-in alias, "mp". For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). -* +- This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS @@ -306,4 +306,6 @@ For more information, see about_Providers. [Rename-ItemProperty](Rename-ItemProperty.md) -[Set-ItemProperty](Set-ItemProperty.md) \ No newline at end of file +[Set-ItemProperty](Set-ItemProperty.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/New-Item.md b/reference/6/Microsoft.PowerShell.Management/New-Item.md index 83a598b2681f..8423241c4236 100644 --- a/reference/6/Microsoft.PowerShell.Management/New-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/New-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,102 +7,111 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821604 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: New-Item --- - # New-Item ## SYNOPSIS + Creates a new item. ## SYNTAX ### pathSet (Default) + ``` New-Item [-Path] [-ItemType ] [-Value ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ### nameSet + ``` New-Item [[-Path] ] -Name [-ItemType ] [-Value ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ## DESCRIPTION -The **New-Item** cmdlet creates a new item and sets its value. + +The `New-Item` cmdlet creates a new item and sets its value. The types of items that can be created depend on the location of the item. -For example, in the file system, **New-Item** creates files and folders. -In the registry, **New-Item** creates registry keys and entries. +For example, in the file system, `New-Item` creates files and folders. +In the registry, `New-Item` creates registry keys and entries. -**New-Item** can also set the value of the items that it creates. -For example, when it creates a new file, **New-Item** can add initial content to the file. +`New-Item` can also set the value of the items that it creates. +For example, when it creates a new file, `New-Item` can add initial content to the file. ## EXAMPLES ### Example 1: Create a file in the current directory -``` -PS C:\> New-Item -Path . -Name "testfile1.txt" -ItemType "file" -Value "This is a text string." -``` -This command creates a text file that is named testfile1.txt in the current directory. -The dot (.) in the value of the *Path* parameter indicates the current directory. -The quoted text that follows the *Value* parameter is added to the file as content. +This command creates a text file that is named "testfile1.txt" in the current directory. +The dot ('.') in the value of the **Path** parameter indicates the current directory. +The quoted text that follows the **Value** parameter is added to the file as content. -### Example 2: Create a directory -``` -PS C:\> New-Item -Path "c:\" -Name "logfiles" -ItemType "directory" +```powershell +New-Item -Path . -Name "testfile1.txt" -ItemType "file" -Value "This is a text string." ``` -This command creates a directory named Logfiles in the C: drive. -The *ItemType* parameter specifies that the new item is a directory, not a file or other file system object. +### Example 2: Create a directory + +This command creates a directory named "Logfiles" in the `C:` drive. +The **ItemType** parameter specifies that the new item is a directory, not a file or other file system object. -### Example 3: Create a profile -``` -PS C:\> New-Item -Path $profile -ItemType "file" -Force +```powershell +New-Item -Path "c:\" -Name "logfiles" -ItemType "directory" ``` -This command creates a PowerShell profile in the path that is specified by the $profile variable. +### Example 3: Create a profile + +This command creates a PowerShell profile in the path that is specified by the `$profile` variable. You can use profiles to customize PowerShell. -$Profile is an automatic (built-in) variable that stores the path and file name of the CurrentUser/CurrentHost profile. +`$profile` is an automatic (built-in) variable that stores the path and file name of the "CurrentUser/CurrentHost" profile. By default, the profile does not exist, even though PowerShell stores a path and file name for it. -In this command, the $profile variable represents the path of the file. -*ItemType* parameter specifies that the command creates a file. -The *Force* parameter lets you create a file in the profile path, even when the directories in the path do not exist. -PowerShell creates them. +In this command, the `$profile` variable represents the path of the file. +**ItemType** parameter specifies that the command creates a file. +The **Force** parameter lets you create a file in the profile path, even when the directories in the path do not exist. After you use this command to create a profile, you can enter aliases, functions, and scripts in the profile to customize your shell. -For more information, see about_Automatic_Variables and about_Profiles. +For more information, see [about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md) and [about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md). -### Example 4: Create a directory in a different directory -``` -PS C:\> New-Item -ItemType "directory" -Path "c:\ps-test\scripts" +```powershell +New-Item -Path $profile -ItemType "file" -Force ``` -This command creates a new Scripts directory in the C:\PS-Test directory. +### Example 4: Create a directory in a different directory + +This command creates a new Scripts directory in the "C:\PS-Test" directory. -The name of the new directory item, Scripts, is included in the value of *Path* parameter, instead of being specified in the value of *Name*. +The name of the new directory item, "Scripts", is included in the value of **Path** parameter, instead of being specified in the value of **Name**. As indicated by the syntax, either command form is valid. -### Example 5: Create multiple files -``` -PS C:\> New-Item -ItemType "file" -Path "c:\ps-test\test.txt", "c:\ps-test\Logs\test.log" +```powershell +New-Item -ItemType "directory" -Path "c:\ps-test\scripts" ``` +### Example 5: Create multiple files + This command creates files in two different directories. -Because *Path* takes multiple strings, you can use it to create multiple items. +Because **Path** takes multiple strings, you can use it to create multiple items. + +```powershell +New-Item -ItemType "file" -Path "c:\ps-test\test.txt", "c:\ps-test\Logs\test.log" +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, this cmdlet prompts you for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -111,16 +120,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Force + Forces this cmdlet to create an item that writes over an existing read-only item. Implementation varies from provider to provider. -For more information, see about_Providers. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +Even using the **Force** parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter @@ -135,6 +145,7 @@ Accept wildcard characters: False ``` ### -ItemType + Specifies the provider-specified type of the new item. Starting in Windows PowerShell 5.0, you can create symbolic links by specifying SymbolicLink as the value of this parameter. @@ -151,6 +162,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the new item. You can specify the name of the new item in the *Name* or *Path* parameter value, and you can specify the path of the new item in *Name* or *Path* value. @@ -168,6 +180,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path of the location of the new item. Wildcard characters are permitted. @@ -198,8 +211,9 @@ Accept wildcard characters: False ``` ### -Value + Specifies the value of the new item. -You can also pipe a value to **New-Item**. +You can also pipe a value to `New-Item`. ```yaml Type: Object @@ -214,6 +228,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -229,6 +244,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -244,42 +260,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.Object + You can pipe a value for the new item to this cmdlet. ## OUTPUTS ### System.Object + This cmdlet returns the item that it creates. ## NOTES -* **New-Item** is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. -* +- `New-Item` is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. ## RELATED LINKS @@ -297,4 +296,6 @@ This cmdlet returns the item that it creates. [Rename-Item](Rename-Item.md) -[Set-Item](Set-Item.md) \ No newline at end of file +[Set-Item](Set-Item.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/New-ItemProperty.md b/reference/6/Microsoft.PowerShell.Management/New-ItemProperty.md index db048eb6e337..5d59d4fd260c 100644 --- a/reference/6/Microsoft.PowerShell.Management/New-ItemProperty.md +++ b/reference/6/Microsoft.PowerShell.Management/New-ItemProperty.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -37,13 +37,21 @@ The `New-ItemProperty` cmdlet creates a new property for a specified item and se Typically, this cmdlet is used to create new registry values, because registry values are properties of a registry key item. This cmdlet does not add properties to an object. -To add a property to an instance of an object, use the `Add-Member` cmdlet. -To add a property to all objects of a particular type, modify the Types.ps1xml file. + +- To add a property to an instance of an object, use the `Add-Member` cmdlet. +- To add a property to all objects of a particular type, modify the Types.ps1xml file. ## EXAMPLES ### Example 1: Add a registry entry +This command adds a new registry entry, "NoOfEmployees", to the "MyCompany" key of the "HKLM:\Software hive". + +The first command uses the **Path** parameter to specify the path of the "MyCompany" registry key. +It uses the **Name** parameter to specify a name for the entry and the **Value** parameter to specify its value. + +The second command uses the `Get-ItemProperty` cmdlet to see the new registry entry. + ```powershell New-ItemProperty -Path "HKLM:\Software\MyCompany" -Name "NoOfEmployees" -Value 822 Get-ItemProperty "HKLM:\Software\MyCompany" @@ -59,30 +67,25 @@ NoOfLocations : 2 NoOfEmployees : 822 ``` -This command adds a new registry entry, NoOfEmployees, to the MyCompany key of the HKLM:\Software hive. - -The first command uses the *Path* parameter to specify the path of the MyCompany registry key. -It uses the *Name* parameter to specify a name for the entry and the *Value* parameter to specify its value. +### Example 2: Add a registry entry to a key -The second command uses the `Get-ItemProperty` cmdlet to see the new registry entry. +This command adds a new registry entry to a registry key. +To specify the key, it uses a pipeline operator (|) to send an object that represents the key to `New-ItemProperty`. -### Example 2: Add a registry entry to a key +The first part of the command uses the `Get-Item` cmdlet to get the "MyCompany" registry key. +The pipeline operator sends the results of the command to `New-ItemProperty`, which adds the new registry entry ("NoOfLocations"), and its value (3), to the "MyCompany" key. ```powershell Get-Item -Path "HKLM:\Software\MyCompany" | New-ItemProperty -Name NoOfLocations -Value 3 ``` -This command adds a new registry entry to a registry key. -To specify the key, it uses a pipeline operator (|) to send an object that represents the key to `New-ItemProperty`. - -The first part of the command uses the `Get-Item` cmdlet to get the MyCompany registry key. -The pipeline operator sends the results of the command to `New-ItemProperty`, which adds the new registry entry, NoOfLocations, and its value, 3, to the MyCompany key. - -This command works because the parameter-binding feature of Windows PowerShell associates the path of the `RegistryKey` object that `Get-Item` returns with the *LiteralPath* parameter of `New-ItemProperty`. +This command works because the parameter-binding feature of Windows PowerShell associates the path of the `RegistryKey` object that `Get-Item` returns with the **LiteralPath** parameter of `New-ItemProperty`. For more information, see [about_Pipelines](../Microsoft.PowerShell.Core/About/about_pipelines.md). ### Example 3: Create a MultiString value in the registry using a Here-String +This example creates a MultiString value using a Here-String. + ```powershell $newValue = New-ItemProperty -Path "HKLM:\SOFTWARE\ContosoCompany\" -Name 'HereString' -PropertyType MultiString -Value @" This is text which contains newlines @@ -96,10 +99,10 @@ This is text which contains newlines It can also contain "quoted" strings ``` -This example creates a MultiString value using a Here-String. - ### Example 4: Create a MultiString value in the registry using an array +The example shows how to use an array of values to create the `MultiString` value. + ```powershell $newValue = New-ItemProperty -Path "HKLM:\SOFTWARE\ContosoCompany\" -Name 'MultiString' -PropertyType MultiString -Value ('a','b','c') $newValue.multistring[0] @@ -109,8 +112,6 @@ $newValue.multistring[0] a ``` -The example shows how to use an array of values to create the `MultiString` value. - ## PARAMETERS ### -Credential @@ -118,10 +119,11 @@ The example shows how to use an array of values to create the `MultiString` valu Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. -If you type a user name, this cmdlet prompts you for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -137,7 +139,9 @@ Accept wildcard characters: False ### -Exclude -Specifies items that this cmdlet omits. +Specifies, as a string array, a property or property that this cmdlet excludes from the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. ```yaml @@ -155,10 +159,10 @@ Accept wildcard characters: True ### -Filter Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the `Path` parameter. +The value of this parameter qualifies the **Path** parameter. The syntax of the filter, including the use of wildcard characters, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when it retrieves the objects instead of having Windows PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -176,7 +180,7 @@ Accept wildcard characters: True Forces the cmdlet to create a property on an object that cannot otherwise be accessed by the user. Implementation varies from provider to provider. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml Type: SwitchParameter @@ -192,9 +196,9 @@ Accept wildcard characters: False ### -Include -Specifies items that this cmdlet includes. -The value of this parameter qualifies the `Path` parameter. -Enter a path element or pattern, such as `*.txt`. +Specifies, as a string array, an item or items that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. ```yaml @@ -211,11 +215,11 @@ Accept wildcard characters: True ### -LiteralPath -Specifies a path of the item property. -The value of the *LiteralPath* parameter is used exactly as it is typed. -No characters are interpreted as wildcard characters. +Specifies the path to the current location of the property. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -268,26 +272,26 @@ Accept wildcard characters: False Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- String. +- **String**: Specifies a null-terminated string. - Equivalent to REG_SZ. -- ExpandString. + 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. + Equivalent to **REG_EXPAND_SZ**. +- **Binary**: Specifies binary data in any form. - Equivalent to REG_BINARY. -- DWord. + Equivalent to **REG_BINARY**. +- **DWord**: Specifies a 32-bit binary number. - Equivalent to REG_DWORD. -- MultiString. + Equivalent to **REG_DWORD**. +- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to REG_MULTI_SZ. -- Qword. + 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. + Equivalent to **REG_QWORD**. +- **Unknown**: + Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. ```yaml Type: String @@ -353,7 +357,7 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS diff --git a/reference/6/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/6/Microsoft.PowerShell.Management/New-PSDrive.md index ebc4ab4d871c..53a78fe24d4b 100644 --- a/reference/6/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/6/Microsoft.PowerShell.Management/New-PSDrive.md @@ -33,8 +33,7 @@ However, because temporary drives are known only to PowerShell, you cannot acces The following features are added to `New-PSDrive` in Windows PowerShell 3.0: -* **Mapped network drives** - +- Mapped network drives. You can use the **Persist** parameter of `New-PSDrive` to create Windows mapped network drives. Unlike temporary PowerShell drives, Windows mapped network drives are not session-specific. They are saved in Windows and they can be managed by using standard Windows tools, such as File Explorer and Net Use. @@ -42,17 +41,14 @@ The following features are added to `New-PSDrive` in Windows PowerShell 3.0: When your command is scoped locally (no dot-sourcing), the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which the command is running. If you are running `New-PSDrive` inside a script, and you want the drive to persist indefinitely, you must dot-source the script. For best results, to force a new drive to persist indefinitely, add the **Scope** parameter to your command, and set its value to Global. - -* **External drives** - +- External drives. When an external drive is connected to the computer, PowerShell automatically adds a **PSDrive** to the file system that represents the new drive. You do not have to restart PowerShell. Similarly, when an external drive is disconnected from the computer, PowerShell automatically deletes the **PSDrive** that represents the removed drive. +- Credentials for UNC Paths. -* **Credentials for UNC Paths** - - When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. - Otherwise, **Credential** is not effective when you are creating new file system drives. +When the value of the **Root** parameter is a UNC path, such as \\\\Server\Share, the credential specified in the value of the **Credential** parameter is used to create the **PSDrive**. +Otherwise, **Credential** is not effective when you are creating new file system drives. ## EXAMPLES @@ -70,7 +66,7 @@ P FileSystem \\Server01\Public This command creates a temporary PowerShell drive named P: that is mapped to the \\\\Server01\Public network share. -It uses the *Name* parameter to specify a name for the drive, the *PSProvider* parameter to specify the PowerShell FileSystem provider, and the *Root* parameter to specify the network share. +It uses the **Name** parameter to specify a name for the drive, the **PSProvider** parameter to specify the PowerShell FileSystem provider, and the **Root** parameter to specify the network share. When the command finishes, the contents of the \\\\Server01\Public share appear in the P: drive. To see them, type: `dir P:`. @@ -90,9 +86,9 @@ MyDocs FileSystem C:\Documents and Settings\User01\My Documents This command creates a temporary PowerShell drive that provides quick access to a local directory. It creates a drive named MyDocs: that is mapped to the "C:\Documents and Settings\User01\My Documents" directory on the local computer. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell FileSystem provider, *Root* to specify the path of the My Documents folder, and the *Description* parameter to create a description of the drive. +It uses *Name* to specify a name for the drive, **PSProvider** to specify the PowerShell FileSystem provider, **Root** to specify the path of the My Documents folder, and the **Description** parameter to create a description of the drive. -When the command finishes, the contents of the My Documents folder appear in the MyDocs: drive. +When the command finishes, the contents of the My Documents folder appear in the `MyDocs:` drive. To see them, type: `dir MyDocs:`. ### Example 3: Create a drive for a registry key @@ -110,9 +106,9 @@ MyCompany Registry HKEY_LOCAL_MACHINE\Software\MyCo... This command creates a temporary PowerShell drive that provides quick access to a frequently checked registry key. It creates a drive named MyCompany that is mapped to the `HKLM\Software\MyCompany` registry key. -It uses *Name* to specify a name for the drive, *PSProvider* to specify the PowerShell Registry provider, and *Root* to specify the registry key. +It uses *Name* to specify a name for the drive, **PSProvider** to specify the PowerShell Registry provider, and **Root** to specify the registry key. -When the command finishes, the contents of the MyCompany key appear in the MyCompany: drive. +When the command finishes, the contents of the MyCompany key appear in the `MyCompany:` drive. To see them, type: `dir MyCompany:`. ### Example 4: Create a persisted mapped network drive @@ -128,14 +124,14 @@ Status Local Remote Network OK S: \\Server01\Scripts Microsoft Windows Network ``` -This command creates the S mapped network drive on the local computer. +This command creates the 'S' mapped network drive on the local computer. The 'S' drive is mapped to the \\\\Server01\Scripts network share. The command uses `New-PSDrive` to create the mapped network drive. It uses *Persist* to create a Windows mapped network drive that is saved on the local computer. -The command uses *Name* to specify a letter name that Windows accepts and *Root* to specify a location on a remote computer. -It uses *PSProvider* to specify the FileSystem provider. +The command uses **Name** to specify a letter name that Windows accepts and **Root** to specify a location on a remote computer. +It uses **PSProvider** to specify the FileSystem provider. The resulting drive can be viewed in other PowerShell sessions on the local computer, in Windows Explorer, and in other tools, such as Net Use. @@ -200,7 +196,7 @@ X: \\products\public Disconnected This example shows the difference between a persistent mapped network drive and a temporary PowerShell drive that is mapped to the same network share. -If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the X: drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. +If you close the PowerShell session and then open a new one, the PSDrive: drive is gone, and the `X:` drive persists. Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it has to be persistent, and whether the drive has to be visible to other Windows features. ## PARAMETERS @@ -209,10 +205,10 @@ If you close the PowerShell session and then open a new one, the PSDrive: drive Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, this cmdlet prompts you for a password. -Starting in Windows PowerShell 3.0, when the value of the *Root* parameter is a UNC path, you can use credentials to create file system drives. +Starting in Windows PowerShell 3.0, when the value of the **Root** parameter is a UNC path, you can use credentials to create file system drives. This parameter is not supported by all PowerShell providers. ```yaml @@ -271,13 +267,13 @@ Indicates that this cmdlet creates a Windows mapped network drive. Mapped network drives are saved in Windows on the local computer. They are persistent, not session-specific, and can be viewed and managed in File Explorer and other tools. -When you scope the command locally, that is, without dot-sourcing, the *Persist* parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. +When you scope the command locally, that is, without dot-sourcing, the **Persist** parameter does not persist the creation of a **PSDrive** beyond the scope in which you run the command. If you run `New-PSDrive` inside a script, and you want the new drive to persist indefinitely, you must dot-source the script. -For best results, to force a new drive to persist, specify Global as the value of the *Scope* parameterin addition to adding *Persist* to your command. +For best results, to force a new drive to persist, specify Global as the value of the **Scope** parameter in addition to adding **Persist** to your command. -The name of the drive must be a letter, such as D or E. -The value of *Root* parameter must be a UNC path of a different computer. -The value of the *PSProvider* parameter must be FileSystem. +The name of the drive must be a letter, such as 'D' or 'E'. +The value of **Root** parameter must be a UNC path of a different computer. +The value of the **PSProvider** parameter must be FileSystem. To disconnect a Windows mapped network drive, use the `Remove-PSDrive` cmdlet. When you disconnect a Windows mapped network drive, the mapping is permanently deleted from the computer, not just deleted from the current session. @@ -395,7 +391,7 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS diff --git a/reference/6/Microsoft.PowerShell.Management/Remove-Item.md b/reference/6/Microsoft.PowerShell.Management/Remove-Item.md index fa2b066109ce..6886fe2e5e7e 100644 --- a/reference/6/Microsoft.PowerShell.Management/Remove-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Remove-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,92 +7,102 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821616 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Remove-Item --- - # Remove-Item ## SYNOPSIS + Deletes the specified items. ## SYNTAX ### Path (Default) + ``` Remove-Item [-Path] [-Filter ] [-Include ] [-Exclude ] [-Recurse] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Stream ] [] ``` ### LiteralPath + ``` Remove-Item -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Recurse] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Stream ] [] ``` ## DESCRIPTION -The **Remove-Item** cmdlet deletes one or more items. + +The `Remove-Item` cmdlet deletes one or more items. Because it is supported by many providers, it can delete many different types of items, including files, folders, registry keys, variables, aliases, and functions. ## EXAMPLES ### Example 1: Delete files that have any file name extension -``` -PS C:\> Remove-Item C:\Test\*.* -``` -This command deletes all of the files that have names that include a dot (.) from the C:\Test folder. +This command deletes all of the files that have names that include a dot ('.') from the "C:\Test" folder. Because the command specifies a dot, the command does not delete folders or files that have no file name extension. -### Example 2: Delete some of the document files in a folder -``` -PS C:\> Remove-Item * -Include *.doc -Exclude *1* +```powershell +Remove-Item C:\Test\*.* ``` -This command deletes from the current folder all files that have a .doc file name extension and a name that does not include 1. -It uses the wildcard character (*) to specify the contents of the current folder. -It uses the *Include* and *Exclude* parameters to specify the files to delete. +### Example 2: Delete some of the document files in a folder -### Example 3: Delete hidden, read-only files -``` -PS C:\> Remove-Item -Path C:\Test\hidden-RO-file.txt -Force +This command deletes from the current folder all files that have a ".doc" file name extension and a name that does not include 1. +It uses the wildcard character ('*') to specify the contents of the current folder. +It uses the **Include** and **Exclude** parameters to specify the files to delete. + +```powershell +Remove-Item * -Include *.doc -Exclude *1* ``` -This command deletes a file that is both hidden and read-only. -It uses the *Path* parameter to specify the file. -It uses the *Force* parameter to delete it. -Without *Force*, you cannot delete read-only or hidden files. +### Example 3: Delete hidden, read-only files -### Example 4: Delete files in subfolders recursively -``` -PS C:\> Get-ChildItem * -Include *.csv -Recurse | Remove-Item +This command deletes a file that is both *hidden* and *read-only*. +It uses the **Path** parameter to specify the file. +It uses the **Force** parameter to delete it. +Without **Force**, you cannot delete *read-only* or *hidden* files. + +```powershell +Remove-Item -Path C:\Test\hidden-RO-file.txt -Force ``` -This command deletes all of the CSV files in the current folder and all subfolder recursively. +### Example 4: Delete files in subfolders recursively -Because the *Recurse* parameter in **Remove-Item** has a known issue, the command in this example uses **Get-ChildItem** to get the desired files, and then uses the pipeline operator to pass them to **Remove-Item**. +This command deletes all of the CSV files in the current folder and all subfolders recursively. -In the **Get-ChildItem** command, *Path* has a value of *, which represents the contents of the current folder. -It uses *Include* to specify the CSV file type, and it uses *Recurse* to make the retrieval recursive. +Because the **Recurse** parameter in `Remove-Item` has a known issue, the command in this example uses `Get-ChildItem` to get the desired files, and then uses the pipeline operator to pass them to `Remove-Item`. -If you try to specify the file type the path, such as `-Path *.csv`, the cmdlet interprets the subject of the search to be a file that has no child items, and *Recurse* fails. +In the `Get-ChildItem` command, **Path** has a value of '*', which represents the contents of the current folder. +It uses **Include** to specify the CSV file type, and it uses **Recurse** to make the retrieval recursive. -### Example 5: Delete subkeys recursively -``` -PS C:\> Remove-Item hklm:\software\mycompany\OldApp -Recurse +If you try to specify the file type the path, such as `-Path *.csv`, the cmdlet interprets the subject of the search to be a file that has no child items, and **Recurse** fails. + +```powershell +Get-ChildItem * -Include *.csv -Recurse | Remove-Item ``` -This command deletes the OldApp registry key and all its subkeys and values. -It uses **Remove-Item** to remove the key. -The path is specified, but the optional parameter name (*Path*) is omitted. +### Example 5: Delete subkeys recursively -The *Recurse* parameter deletes all of the contents of the OldApp key recursively. -If the key contains subkeys and you omit the *Recurse* parameter, you are prompted to confirm that you want to delete the contents of the key. +This command deletes the "OldApp" registry key and all its subkeys and values. +It uses `Remove-Item` to remove the key. +The path is specified, but the optional parameter name (**Path**) is omitted. -### Example 6 - Deleting files with special characters +The **Recurse** parameter deletes all of the contents of the "OldApp" key recursively. +If the key contains subkeys and you omit the **Recurse** parameter, you are prompted to confirm that you want to delete the contents of the key. + +```powershell +Remove-Item HKLM:\Software\MyCompany\OldApp -Recurse +``` + +### Example 6: Deleting files with special characters The following example shows how to delete files that contain special characters like brackets or parentheses. +```powershell +Get-ChildItem ``` -PS C:\temp\Downloads> Get-ChildItem +```output Directory: C:\temp\Downloads Mode LastWriteTime Length Name @@ -102,8 +112,13 @@ Mode LastWriteTime Length Name -a---- 6/1/2018 12:19 PM 1283 myFile[2].txt -a---- 6/1/2018 12:19 PM 1432 myFile[3].txt -PS C:\temp\Downloads> Get-ChildItem | Where-Object Name -Like '*`[*' +``` + +```powershell +Get-ChildItem | Where-Object Name -Like '*`[*' +``` +```output Directory: C:\temp\Downloads Mode LastWriteTime Length Name @@ -112,9 +127,14 @@ Mode LastWriteTime Length Name -a---- 6/1/2018 12:19 PM 1283 myFile[2].txt -a---- 6/1/2018 12:19 PM 1432 myFile[3].txt -PS C:\temp\Downloads> Get-ChildItem | Where-Object Name -Like '*`[*' | ForEach-Object { Remove-Item -LiteralPath $_.Name } -PS C:\temp\Downloads> Get-ChildItem +``` +```powershell +Get-ChildItem | Where-Object Name -Like '*`[*' | ForEach-Object { Remove-Item -LiteralPath $_.Name } +Get-ChildItem +``` + +```output Directory: C:\temp\Downloads Mode LastWriteTime Length Name @@ -122,9 +142,64 @@ Mode LastWriteTime Length Name -a---- 6/1/2018 12:19 PM 1362 myFile.txt ``` +### Example 7: Remove an alternate data stream + +This example shows how to use the Stream dynamic parameter of the `Remove-Item` cmdlet to delete an alternate data stream. The stream parameter is introduced in Windows PowerShell 3.0. + +The first command uses the **Stream** dynamic parameter of the `Get-Item` cmdlet to get the **Zone.Identifier** stream of the "Copy-Script.ps1" file. + +The second command uses the **Stream** dynamic parameter of the `Remove-Item` cmdlet to remove the **Zone.Identifier** stream of the file. + +The third command uses the **Stream** dynamic parameter of the `Get-Item` cmdlet to verify that the **Zone.Identifier** stream is deleted. + +The fourth command `Get-Item` cmdlet without the **Stream** parameter to verify that the file is not deleted. + +```powershell +Get-Item C:\Test\Copy-Script.ps1 -Stream Zone.Identifier +``` + +```output + FileName: \\C:\Test\Copy-Script.ps1 + +Stream Length +------ ------ +Zone.Identifier 26 + +``` + +```powershell +Remove-Item C:\Test\Copy-Script.ps1 -Stream Zone.Identifier + +Get-Item C:\Test\Copy-Script.ps1 -Stream Zone.Identifier +``` + +```output +Get-Item : Could not open alternate data stream 'Zone.Identifier' of file 'C:\Test\Copy-Script.ps1'. +At line:1 char:1 ++ Get-Item 'C:\Test\Copy-Script.ps1' -Stream Zone.Identifier ++ [!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()]~~ + + CategoryInfo : ObjectNotFound: (C:\Test\Copy-Script.ps1:String) [Get-Item], FileNotFoundE + xception + + FullyQualifiedErrorId : AlternateDataStreamNotFound,Microsoft.PowerShell.Commands.GetItemCommand + +``` + +```powershell +Get-Item C:\Test\Copy-Script.ps1 +``` + +```output + Directory: C:\Test + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 8/4/2011 11:15 AM 9436 Copy-Script.ps1 +``` + ## PARAMETERS ### -Stream + Specifies an alternative data stream from a file that this cmdlet deletes. This cmdlet does not delete the file. Enter the stream name. @@ -132,12 +207,12 @@ Wildcard characters are supported. This parameter is not valid on folders. -The *Stream* parameter is a dynamic parameter that the FileSystem provider adds to **Remove-Item**. +The **Stream** parameter is a dynamic parameter that the FileSystem provider adds to `Remove-Item`. This parameter works only in file system drives. -You can use **Remove-Item** to delete an alternative data stream. +You can use `Remove-Item` to delete an alternative data stream. However, it is not the recommended way to eliminate security checks that block files that are downloaded from the Internet. -If you verify that a downloaded file is safe, use the Unblock-File cmdlet. +If you verify that a downloaded file is safe, use the `Unblock-File` cmdlet. This parameter was introduced in Windows PowerShell 3.0. @@ -154,13 +229,15 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, this cmdlet prompts you for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -169,14 +246,15 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as *.txt. Wildcard characters are permitted. @@ -193,10 +271,12 @@ Accept wildcard characters: False ``` ### -Filter + Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. + The syntax of the filter, including the use of wildcard characters, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when it retrieves the objects, instead of having PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -207,15 +287,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Forces the cmdlet to remove items that cannot otherwise be changed, such as hidden or read-only files or read-only aliases or variables. The cmdlet cannot remove constant aliases or variables. Implementation varies from provider to provider. -For more information, see about_Providers. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +Even using the **Force** parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter @@ -224,15 +305,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include + Specifies items to delete. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. ```yaml @@ -248,9 +330,10 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies a path of the items being removed. -Unlike **Path**, the value of the *LiteralPath* parameter is used exactly as it is typed. -No characters are interpreted as wildcard characters. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -267,6 +350,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies a path of the items being removed. Wildcard characters are permitted. @@ -283,11 +367,12 @@ Accept wildcard characters: True ``` ### -Recurse + Indicates that this cmdlet deletes the items in the specified locations and in all child items of the locations. -When it is used with the *Include* parameter, the *Recurse* parameter might not delete all subfolders or all child items. +When it is used with the **Include** parameter, the **Recurse** parameter might not delete all subfolders or all child items. This is a known issue. -As a workaround, try piping results of the `Get-ChildItem -Recurse` command to **Remove-Item**, as described in Example 4 in this topic. +As a workaround, try piping results of the `Get-ChildItem -Recurse` command to `Remove-Item`, as described in "Example 4" in this topic. ```yaml Type: SwitchParameter @@ -302,6 +387,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -317,6 +403,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -332,41 +419,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path, but not a literal path, to this cmdlet. ## OUTPUTS ### None + This cmdlet does not return any output. ## NOTES -* You can also refer to **Remove-Item** by any of its built-in aliases: **del**, **erase**, **rmdir**, **rd**, **ri**, or **rm**. For more information, see about_Aliases. -* **Remove-Item** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. + +The `Remove-Item` cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS @@ -387,3 +458,5 @@ This cmdlet does not return any output. [Rename-Item](Rename-Item.md) [Set-Item](Set-Item.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Remove-ItemProperty.md b/reference/6/Microsoft.PowerShell.Management/Remove-ItemProperty.md index 9a1b0d1d4cd3..402ed870674a 100644 --- a/reference/6/Microsoft.PowerShell.Management/Remove-ItemProperty.md +++ b/reference/6/Microsoft.PowerShell.Management/Remove-ItemProperty.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821617 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Remove-ItemProperty --- - # Remove-ItemProperty ## SYNOPSIS + Deletes the property and its value from an item. ## SYNTAX ### Path (Default) + ``` Remove-ItemProperty [-Path] [-Name] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-InformationAction ] @@ -23,6 +24,7 @@ Remove-ItemProperty [-Path] [-Name] [-Force] [-Filter [-Name] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -30,58 +32,64 @@ Remove-ItemProperty -LiteralPath [-Name] [-Force] [-Filter ``` ## DESCRIPTION -The **Remove-ItemProperty** cmdlet deletes a property and its value from an item. + +The `Remove-ItemProperty` cmdlet deletes a property and its value from an item. You can use it to delete registry values and the data that they store. ## EXAMPLES ### Example 1: Delete a registry value -``` -PS C:\> Remove-ItemProperty -Path "HKLM:\Software\SmpApplication" -Name "SmpProperty" -``` -This command deletes the SmpProperty registry value, and its data, from the SmpApplication subkey of the HKEY_LOCAL_MACHINE\Software registry key. +This command deletes the "SmpProperty" registry value, and its data, from the "SmpApplication" subkey of the "HKEY_LOCAL_MACHINE\Software" registry key. -Because the command is issued from a file system drive (PS C:\\\>), it includes the fully qualified path of the SmpApplication subkey, including the drive, HKLM:, and the Software key. +Because the command is issued from a file system drive (`PS C:\>`), it includes the fully qualified path of the "SmpApplication" subkey, including the drive, `HKLM:`, and the "Software" key. -It uses the *Name* parameter to identify the registry value that is being deleted. +It uses the **Name** parameter to identify the registry value that is being deleted. + +```powershell +Remove-ItemProperty -Path "HKLM:\Software\SmpApplication" -Name "SmpProperty" +``` ### Example 2: Delete a registry value from the HKCU location + +These commands delete the "Options" registry value, and its data, from the "MyApp" subkey of "HKEY_CURRENT_USER\Software\MyCompany". + +The first command uses the `Set-Location` cmdlet to change the current location to the **HKEY_CURRENT_USER** drive (`HKCU:`) and the "Software\MyCompany\MyApp" subkey. + +The second command uses `Remove-ItemProperty` to remove the "Options" registry value, and its data, from the "MyApp" subkey. +Because **Path** is required, the command uses a dot ('.') to indicate the current location. +It uses **Name** to specify which registry value to delete. +It uses the **Confirm** parameter to request a user prompt before deleting the value. + ``` PS C:\> Set-Location HKCU:\Software\MyCompany\MyApp PS HKCU:\Software\MyCompany\MyApp> Remove-ItemProperty -Path . -Name "Options" -Confirm ``` -These commands delete the Options registry value, and its data, from the MyApp subkey of HKEY_CURRENT_USER\Software\MyCompany. +### Example 3: Remove a registry value by using the pipeline -The first command uses the Set-Location cmdlet to change the current location to the HKEY_CURRENT_USER drive (HKCU:) and the Software\MyCompany\MyApp subkey. +This command deletes the "NoOfEmployees" registry value, and its data, from the "HKLM\Software\MyCompany" registry key. -The second command uses **Remove-ItemProperty** to remove the Options registry value, and its data, from the MyApp subkey. -Because *Path* is required, the command uses a dot (.) to indicate the current location. -It uses *Name* to specify which registry value to delete. -It uses the *Confirm* parameter to request a user prompt before deleting the value. +The command uses the `Get-Item` cmdlet to get an item that represents the registry key. +It uses a pipeline operator (`|`) to send the object to `Remove-ItemProperty`. +Then, it uses the **Name** parameter of `Remove-ItemProperty` to specify the name of the registry value. -### Example 3: Remove a registry value by using the pipeline +```powershell +Get-Item -Path HKLM:\Software\MyCompany | Remove-ItemProperty -Name NoOfEmployees ``` -PS C:\> Get-Item -Path HKLM:\Software\MyCompany | Remove-ItemProperty -Name NoOfEmployees -``` - -This command deletes the NoOfEmployees registry value, and its data, from the HKLM\Software\MyCompany registry key. - -The command uses the Get-Item cmdlet to get an item that represents the registry key. -It uses a pipeline operator (|) to send the object to **Remove-ItemProperty**. -Then, it uses the *Name* parameter of **Remove-ItemProperty** to specify the name of the registry value. ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, this cmdlet prompts you for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -90,15 +98,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. ```yaml @@ -110,14 +119,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter + Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. + The syntax of the filter, including the use of wildcard characters, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when it retrieves the objects instead of having PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -128,13 +139,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Forces the cmdlet to remove a property of an object that cannot otherwise be accessed by the user. Implementation varies from provider to provider. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml Type: SwitchParameter @@ -143,15 +155,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include -Specifies items to delete. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. + +Specifies, as a string array, an item or items that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. ```yaml @@ -167,9 +180,10 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies a path of the item property. -The value of the *LiteralPath* parameter is used exactly as it is typed. -No characters are interpreted as wildcard characters. + +Specifies the path to the current location of the property. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -186,6 +200,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the names of the properties to remove. ```yaml @@ -201,6 +216,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path of the item whose properties are being removed. Wildcard characters are permitted. @@ -217,6 +233,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -232,6 +249,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -247,42 +265,27 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path, but not a literal path, to this cmdlet. ## OUTPUTS ### None + This cmdlet does not return any output. ## NOTES -* You can also refer to **Remove-ItemProperty** by its built-in alias, **rp**. For more information, see about_Aliases. -* In the PowerShell Registry provider, registry values are considered to be properties of a registry key or subkey. You can use the **ItemProperty** cmdlets to manage these values. -* **Remove-ItemProperty** is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. + +- You can also refer to `Remove-ItemProperty` by its built-in alias, **rp**. For more information, see about_Aliases. +- In the PowerShell Registry provider, registry values are considered to be properties of a registry key or subkey. You can use the **ItemProperty** cmdlets to manage these values. +- `Remove-ItemProperty` is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. ## RELATED LINKS @@ -304,4 +307,6 @@ This cmdlet does not return any output. [Set-ItemProperty](Set-ItemProperty.md) -[Set-Location](Set-Location.md) \ No newline at end of file +[Set-Location](Set-Location.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Rename-Item.md b/reference/6/Microsoft.PowerShell.Management/Rename-Item.md index 84ce2bd1be0d..2c5a124f1e52 100644 --- a/reference/6/Microsoft.PowerShell.Management/Rename-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Rename-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,102 +7,107 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821621 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Rename-Item --- - # Rename-Item ## SYNOPSIS + Renames an item in a PowerShell provider namespace. ## SYNTAX ### ByPath (Default) + ``` Rename-Item [-Path] [-NewName] [-Force] [-PassThru] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ### ByLiteralPath + ``` Rename-Item -LiteralPath [-NewName] [-Force] [-PassThru] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ## DESCRIPTION -The **Rename-Item** cmdlet changes the name of a specified item. + +The `Rename-Item` cmdlet changes the name of a specified item. This cmdlet does not affect the content of the item being renamed. -You cannot use **Rename-Item** to move an item, such as by specifying a path together with the new name. -To move and rename an item, use the Move-Item cmdlet. +You cannot use `Rename-Item` to move an item, such as by specifying a path together with the new name. +To move and rename an item, use the `Move-Item` cmdlet. ## EXAMPLES ### Example 1: Rename a file -``` -PS C:\> Rename-Item -Path "c:\logfiles\daily_file.txt" -NewName "monday_file.txt" -``` -This command renames the file daily_file.txt to monday_file.txt. +This command renames the file "daily_file.txt" to "monday_file.txt". + +```powershell +Rename-Item -Path "c:\logfiles\daily_file.txt" -NewName "monday_file.txt" +``` ### Example 2: Rename and move an item + +This example shows that you cannot use `Rename-Item` to both rename and move an item. +Specifically, you cannot supply a path for the value of the **NewName** parameter, unless the path is identical to the path specified in the **Path** parameter. +Otherwise, only a new name is permitted. + ``` The first command attempts to rename the project.txt file in the current directory to old-project.txt in the D:\Archive directory. The result is the error shown in the output. -PS C:\> Rename-Item -Path "project.txt" -NewName "d:\archive\old-project.txt" +PS> Rename-Item -Path "project.txt" -NewName "d:\archive\old-project.txt" Rename-Item : Cannot rename because the target specified represents a path or device name. At line:1 char:12 -+ rename-item <<<< -path project.txt -newname d:\archive\old-project.txt -+ CategoryInfo : InvalidArgument: (:) [Rename-Item], PSArgumentException -+ FullyQualifiedErrorId : Argument,Microsoft.PowerShell.Commands.RenameItemCommand - -The second command shows the correct way to move and rename a file by using **Move-Item**. The **Move-Item** cmdlet lets you specify both a new path and a new name in the value of its *Destination* parameter. -PS C:\> Move-Item -Path "project.txt" -Destination "d:\archive\old-project.txt" ++ Rename-Item <<<< -path project.txt -NewName d:\archive\old-project.txt ++ CategoryInfo : InvalidArgument: (:) [Rename-Item], PS> Move-Item -Path "project.txt" -Destination "d:\archive\old-project.txt" ``` -This example shows that you cannot use **Rename-Item** to both rename and move an item. -Specifically, you cannot supply a path for the value of the *NewName* parameter, unless the path is identical to the path specified in the *Path* parameter. -Otherwise, only a new name is permitted. - ### Example 3: Rename a registry key -``` -PS C:\> Rename-Item -Path "HKLM:\Software\MyCompany\Advertising" -NewName "Marketing" -``` -This command renames a registry key from Advertising to Marketing. +This command renames a registry key from "Advertising" to "Marketing". When the command is complete, the key is renamed, but the registry entries in the key are unchanged. -### Example 4: Rename multiple files -``` -PS C:\> Get-ChildItem *.txt | Rename-Item -NewName { $_.name -Replace '\.txt$','.log' } +```powershell +Rename-Item -Path "HKLM:\Software\MyCompany\Advertising" -NewName "Marketing" ``` -This example shows how to use the **Replace** operator to rename multiple files, even though the *NewName* parameter does not accept wildcard characters. +### Example 4: Rename multiple files + +This example shows how to use the **Replace** operator to rename multiple files, even though the **NewName** parameter does not accept wildcard characters. -This command renames all of the .txt files in the current directory to .log. +This command renames all of the ".txt" files in the current directory to ".log". -The command uses the Get-ChildItem cmdlet to get all of the files in the current folder that have a .txt file name extension. -Then, it uses the pipeline operator (|) to send those files to **Rename-Item**. +The command uses the `Get-ChildItem` cmdlet to get all of the files in the current folder that have a .txt file name extension. +Then, it uses the pipeline operator (`|`) to send those files to `Rename-Item`. -The value of *NewName* is a script block that runs before the value is submitted to the *NewName* parameter. +The value of **NewName** is a script block that runs before the value is submitted to the **NewName** parameter. In the script block, the `$_` automatic variable represents each file object as it comes to the command through the pipeline. -The command uses the dot format (.) to get the **Name** property of each file object. -The **Replace** operator replaces the .txt file name extension of each file with .log. +The command uses the dot format ('.') to get the **Name** property of each file object. +The **Replace** operator replaces the ".txt" file name extension of each file with ".log". + +Because the **Replace** operator works with regular expressions, the dot in front of "txt" is interpreted to match any character. +To make sure that it matches only a dot ('.'), it is escaped with a backslash character (\\). +The backslash character is not required in ".log" because it is a string, not a regular expression. -Because the **Replace** operator works with regular expressions, the dot in front of txt is interpreted to match any character. -To make sure that it matches only a dot (.), it is escaped with a backslash character (\\). -The backslash character is not required in .log because it is a string, not a regular expression. +To make sure that ".txt" is an extension, i.e. last part of the string representing the name, a dollar sign (`$`) is added after "\\.txt". -To make sure that .txt is an extension, i.e. last part of the string representing the name, a dollar sign ($) is added after \\.txt. +```powershell +Get-ChildItem *.txt | Rename-Item -NewName { $_.name -Replace '\.txt$','.log' } +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, this cmdlet prompts you for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -111,18 +116,19 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Force + Forces the cmdlet to rename items that cannot otherwise be changed, such as hidden or read-only files or read-only aliases or variables. The cmdlet cannot change constant aliases or variables. Implementation varies from provider to provider. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +Even using the **Force** parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter @@ -137,10 +143,10 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies the path of the item to rename. -Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. -No characters are interpreted as wildcard characters. +Specifies the path of the item to rename. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -157,10 +163,11 @@ Accept wildcard characters: False ``` ### -NewName + Specifies the new name of the item. Enter only a name, not a path and name. -If you enter a path that differs from the path that is specified in the *Path* parameter, **Rename-Item** generates an error. -To rename and move an item, use **Move-Item**. +If you enter a path that differs from the path that is specified in the *Path* parameter, `Rename-Item` generates an error. +To rename and move an item, use `Move-Item`. You cannot use wildcard characters in the value of the *NewName* parameter. To specify a name for multiple files, use the **Replace** operator in a regular expression. @@ -179,6 +186,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object that represents the item to the pipeline. By default, this cmdlet does not generate any output. @@ -195,6 +203,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path of the item to rename. ```yaml @@ -210,6 +219,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -225,6 +235,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -240,43 +251,26 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path to this cmdlet. ## OUTPUTS ### None or an object that represents the renamed item. + This cmdlet generates an object that represents the renamed item, if you specify the *PassThru* parameter. Otherwise, this cmdlet does not generate any output. ## NOTES -* **Rename-Item** is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. -* +- `Rename-Item` is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. ## RELATED LINKS @@ -298,4 +292,6 @@ Otherwise, this cmdlet does not generate any output. [Rename-ItemProperty](Rename-ItemProperty.md) -[Set-Item](Set-Item.md) \ No newline at end of file +[Set-Item](Set-Item.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Rename-ItemProperty.md b/reference/6/Microsoft.PowerShell.Management/Rename-ItemProperty.md index a0557c69c1ac..807c7956986d 100644 --- a/reference/6/Microsoft.PowerShell.Management/Rename-ItemProperty.md +++ b/reference/6/Microsoft.PowerShell.Management/Rename-ItemProperty.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821622 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Rename-ItemProperty --- - # Rename-ItemProperty ## SYNOPSIS + Renames a property of an item. ## SYNTAX ### Path (Default) + ``` Rename-ItemProperty [-Path] [-Name] [-NewName] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -23,6 +24,7 @@ Rename-ItemProperty [-Path] [-Name] [-NewName] [-Pass ``` ### LiteralPath + ``` Rename-ItemProperty -LiteralPath [-Name] [-NewName] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -30,29 +32,33 @@ Rename-ItemProperty -LiteralPath [-Name] [-NewName] [ ``` ## DESCRIPTION -The **Rename-ItemProperty** cmdlet changes the name of a specified item property. + +The `Rename-ItemProperty` cmdlet changes the name of a specified item property. The value of the property is not changed. -For example, you can use **Rename-ItemProperty** to change the name of a registry entry. +For example, you can use `Rename-ItemProperty` to change the name of a registry entry. ## EXAMPLES ### Example 1: Rename a registry entry -``` -PS C:\> Rename-ItemProperty -Path HKLM:\Software\SmpApplication -Name config -NewName oldconfig -``` -This command renames the config registry entry that is contained in the HKEY_LOCAL_MACHINE\Software\SmpApplication key to oldconfig. +This command renames the config registry entry that is contained in the "HKEY_LOCAL_MACHINE\Software\SmpApplication" key to "oldconfig". + +```powershell +Rename-ItemProperty -Path HKLM:\Software\SmpApplication -Name config -NewName oldconfig +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, this cmdlet prompts you for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -61,13 +67,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies items that this cmdlet omits. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. ```yaml @@ -79,14 +88,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter + Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. + The syntax of the filter, including the use of wildcard characters, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when it retrieves the objects instead of having PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -97,13 +108,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Forces the cmdlet to rename a property of an object that cannot otherwise be accessed by the user. Implementation varies from provider to provider. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml Type: SwitchParameter @@ -112,13 +124,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include + Specifies only those items upon which the cmdlet acts, excluding all others. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -129,13 +145,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath + Specifies a path of the item property. -This cmdlet uses the value of the *LiteralPath* cmdlet exactly as it is typed. -No characters are interpreted as wildcard characters. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -152,6 +169,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the current name of the property to rename. ```yaml @@ -167,6 +185,7 @@ Accept wildcard characters: False ``` ### -NewName + Specifies the new name for the property. ```yaml @@ -182,6 +201,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object that represents the item property. By default, this cmdlet does not generate any output. @@ -198,6 +218,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path of the item to rename. ```yaml @@ -213,6 +234,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -228,6 +250,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -243,43 +266,26 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path, but not a literal path, to this cmdlet. ## OUTPUTS ### None, System.Management.Automation.PSCustomObject + This cmdlet generates a **PSCustomObject** that represents the renamed item property, if you specify the *PassThru* parameter. Otherwise, this cmdlet does not generate any output. ## NOTES -* **Remove-ItemProperty** is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. -* +- `Remove-ItemProperty` is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. ## RELATED LINKS @@ -297,4 +303,6 @@ Otherwise, this cmdlet does not generate any output. [Rename-Item](Rename-Item.md) -[Set-ItemProperty](Set-ItemProperty.md) \ No newline at end of file +[Set-ItemProperty](Set-ItemProperty.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Set-Content.md b/reference/6/Microsoft.PowerShell.Management/Set-Content.md index 6483a71bb022..2d67a6fdb0ee 100644 --- a/reference/6/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Set-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 11/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821629 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Set-Content --- - # Set-Content ## SYNOPSIS @@ -18,7 +17,7 @@ Writes or replaces the content in an item with new content. ### Path (Default) -```powershell +``` Set-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -26,7 +25,7 @@ Set-Content [-Value] [-PassThru] [-Path] [-Filter ### LiteralPath -```powershell +``` Set-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -34,16 +33,16 @@ Set-Content [-Value] [-PassThru] -LiteralPath [-Filter Set-Content -Path "C:\Test1\test*.txt" -Value "Hello, World" +Set-Content -Path "C:\Test1\test*.txt" -Value "Hello, World" ``` This command replaces the contents of all files in the Test1 folder that have names that start with "test" with "Hello, World". @@ -52,30 +51,30 @@ This example shows how to specify content by typing it in the command. ### Example 2: Send content to a file ```powershell -PS C:\> Get-Date | Set-Content -Path "C:\Test1\date.csv" +Get-Date | Set-Content -Path "C:\Test1\date.csv" ``` This command creates a comma-separated variable-length (csv) file that contains only the current date and time. -It uses the Get-Date cmdlet to get the current system date and time. -The pipeline operator passes the result to Set-Content, which creates the file and writes the content. +It uses the `Get-Date` cmdlet to get the current system date and time. +The pipeline operator passes the result to `Set-Content`, which creates the file and writes the content. If the Test1 directory does not exist, the command fails, but if the file does not exist, the command creates it. ### Example 3: Replace text in a file ```powershell -PS C:\> (Get-Content -Path "Notice.txt") | ForEach-Object {$_ -Replace "Warning", "Caution"} | Set-Content -Path "Notice.txt" +(Get-Content -Path "Notice.txt") | ForEach-Object {$_ -Replace "Warning", "Caution"} | Set-Content -Path "Notice.txt" ``` This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. -It uses Get-Content cmdlet to get the content of Notice.txt. -The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. +It uses `Get-Content` cmdlet to get the content of Notice.txt. +The pipeline operator sends the results to the `ForEach-Object` cmdlet, which applies the expression to each line of content in `Get-Content`. The expression uses the `$_` symbol to refer to the current item and the Replace parameter to specify the text to be replaced. -Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content. +Another pipeline operator sends the changed content to `Set-Content` which replaces the text in Notice.txt with the new content. -The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. +The parentheses around the `Get-Content` command ensure that the Get operation is complete before the Set operation begins. Without them, the command will fail because the two functions will be trying to access the same file. ## PARAMETERS @@ -101,7 +100,7 @@ Accept wildcard characters: False Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, you will be prompted for a password. This parameter is not supported by any providers installed with PowerShell. @@ -123,20 +122,23 @@ Accept wildcard characters: False Specifies the file encoding. The acceptable values for this parameter are: -- **ASCII** Uses the encoding for the ASCII (7-bit) character set. -- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. -- **BigEndianUTF32** Encodes in UTF-32 format using the big-endian byte order. -- **Default** Encodes using the default value: ASCII. -- **Byte** Encodes a set of characters into a sequence of bytes. -- **String** Uses the encoding type for a string. -- **Unicode** Encodes in UTF-16 format using the little-endian byte order. -- **UTF7** Encodes in UTF-7 format. -- **UTF8** Encodes in UTF-8 format. -- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. +- **ASCII**: Uses the encoding for the ASCII (7-bit) character set. +- **BigEndianUnicode**: Encodes in UTF-16 format using the big-endian byte order. +- **Default**: Encodes using the default value: ASCII. +- **OEM**: Uses the default encoding for MS-DOS and console programs. +- **Byte**: Encodes a set of characters into a sequence of bytes. +- **String**: Uses the encoding type for a string. +- **Unicode**: Encodes in UTF-16 format using the little-endian byte order. +- **UTF7**: Encodes in UTF-7 format. +- **UTF8**: Encodes in UTF-8 format. +- **UTF8BOM**: Encodes in UTF-8 format with Byte Order Mark (BOM) +- **UF8NOBOM**: Encodes in UTF-8 format without Byte Order Mark (BOM) +- **UTF32**: Encodes in UTF-32 format. +- **Unknown**: The encoding type is unknown or invalid; the data can be treated as binary. The default value is ASCII. -Encoding is a dynamic parameter that the FileSystem provider adds to **Set-Content**. +Encoding is a dynamic parameter that the FileSystem provider adds to `Set-Content`. This parameter works only in file system drives. ```yaml @@ -194,10 +196,8 @@ Accept wildcard characters: True ### -Force -Forces the cmdlet to set the contents of a file, even if the file is read-only. -Implementation varies from provider to provider. -For more information, see about_Providers. -Using the Force parameter does not override security restrictions. +Overrides restrictions that prevent the command from succeeding, provided the changes do not compromise security. +For example, **Force** will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions. ```yaml Type: SwitchParameter @@ -313,7 +313,7 @@ This parameter works only in file system drives. You can use the `Set-Content` cmdlet to change the content of the Zone.Identifier alternate data stream. However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. -If you verify that a downloaded file is safe, use the Unblock-File cmdlet. +If you verify that a downloaded file is safe, use the `Unblock-File` cmdlet. This parameter was introduced in PowerShell 3.0. @@ -382,33 +382,30 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters). +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.Object -You can pipe an object that contains the new value for the item to Set-Content. +You can pipe an object that contains the new value for the item to `Set-Content`. ## OUTPUTS ### None or System.String -When you use the Passthru parameter, Set-Content generates a System.String object representing the content. +When you use the **Passthru** parameter, `Set-Content` generates a **System.String** object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -Set-Content is designed for string processing. -If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. -To write objects to files, use Out-File. +`Set-Content` is designed for string processing. +If you pipe non-string objects to `Set-Content`, it converts the object to a string before writing it. +To write objects to files, use `Out-File`. -The Set-Content cmdlet is designed to work with the data exposed by any provider. +The `Set-Content` cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Management/Set-Item.md b/reference/6/Microsoft.PowerShell.Management/Set-Item.md index 8e6b5eec853d..b411a034d6a0 100644 --- a/reference/6/Microsoft.PowerShell.Management/Set-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Set-Item.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,21 +7,23 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821630 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Set-Item --- - # Set-Item ## SYNOPSIS + Changes the value of an item to the value specified in the command. ## SYNTAX ### Path (Default) + ``` Set-Item [-Path] [[-Value] ] [-Force] [-PassThru] [-Filter ] [-Include ] [-Exclude ] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ### LiteralPath + ``` Set-Item -LiteralPath [[-Value] ] [-Force] [-PassThru] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -29,50 +31,57 @@ Set-Item -LiteralPath [[-Value] ] [-Force] [-PassThru] [-Filt ``` ## DESCRIPTION -The **Set-Item** cmdlet changes the value of an item, such as a variable or registry key, to the value specified in the command. + +The `Set-Item` cmdlet changes the value of an item, such as a variable or registry key, to the value specified in the command. ## EXAMPLES ### Example 1: Create an alias -``` -PS C:\> Set-Item -Path alias:np -Value "c:\windows\notepad.exe" -``` This command creates an alias of np for Notepad. -### Example 2: Change the value of an environment variable -``` -PS C:\> Set-Item -Path env:UserRole -Value "Administrator" +```powershell +Set-Item -Path alias:np -Value "c:\windows\notepad.exe" ``` +### Example 2: Change the value of an environment variable + This command changes the value of the UserRole environment variable to Administrator. -### Example 3: Modify your prompt function -``` -PS C:\> Set-Item -Path function:prompt -Value {'PS '+ $(Get-Date -Format t) + " " + $(Get-Location) + '> '} +```powershell +Set-Item -Path env:UserRole -Value "Administrator" ``` +### Example 3: Modify your prompt function + This command changes the prompt function so that it displays the time before the path. -### Example 4: Set options for your prompt function -``` -PS C:\> Set-Item -Path function:prompt -Options "AllScope,ReadOnly" +```powershell +Set-Item -Path function:prompt -Value {'PS '+ $(Get-Date -Format t) + " " + $(Get-Location) + '> '} ``` -This command sets the AllScope and ReadOnly options for the prompt function. -This command uses the *Options* dynamic parameter of **Set-Item**. -The *Options* parameter is available in **Set-Item** only when you use it with the Alias or Function provider. +### Example 4: Set options for your prompt function + +This command sets the **AllScope** and **ReadOnly** options for the prompt function. +This command uses the **Options** dynamic parameter of `Set-Item`. +The **Options** parameter is available in `Set-Item` only when you use it with the **Alias** or **Function** provider. + +```powershell +Set-Item -Path function:prompt -Options "AllScope,ReadOnly" +``` ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, this cmdlet prompts for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -81,15 +90,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. ```yaml @@ -101,14 +111,16 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter + Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. + The syntax of the filter, including the use of wildcard characters, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when it retrieves the objects, instead of having PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -123,10 +135,11 @@ Accept wildcard characters: False ``` ### -Force + Forces the cmdlet to set items that cannot otherwise be changed, such as read-only alias or variables. The cmdlet cannot change constant aliases or variables. Implementation varies from provider to provider. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). Even using the *Force* parameter, the cmdlet cannot override security restrictions. ```yaml @@ -136,15 +149,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include -Specifies items that this cmdlet changes. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. + +Specifies, as a string array, an item or items that this cmdlet includes in the operation. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. ```yaml @@ -160,9 +174,10 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies a path of the location of the new items. -Unlike *Path*, the value of *LiteralPath* is used exactly as it is typed. -No characters are interpreted as wildcard characters. + +Specifies a path of the location of the items. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -179,6 +194,7 @@ Accept wildcard characters: False ``` ### -PassThru + Passes an object that represents the item to the pipeline. By default, this cmdlet does not generate any output. @@ -195,7 +211,8 @@ Accept wildcard characters: False ``` ### -Path -Specifies a path of the location of the new items. + +Specifies a path of the location of the items. Wildcard characters are permitted. ```yaml @@ -211,6 +228,7 @@ Accept wildcard characters: False ``` ### -Value + Specifies a new value for the item. ```yaml @@ -226,6 +244,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -241,6 +260,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -256,55 +276,38 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.Object + You can pipe an object that represents the new value of the item to this cmdlet. ## OUTPUTS ### None or an object representing the new or changed item. + This cmdlet generates an object that represent the item, if you specify the *PassThru* parameter. Otherwise, this cmdlet does not generate any output. ## NOTES -* You can also refer to **Set-Item** by its built-in alias, **si**. For more information, see about_Aliases. - **Set-Item** is not supported by the PowerShell FileSystem provider. -To change the values of items in the file system, use the Set-Content cmdlet. +- You can also refer to `Set-Item` by its built-in alias, **si**. For more information, see about_Aliases. - In the Registry drives, HKLM: and HKCU:, **Set-Item** changes the data in the (Default) value of a registry key. -To create and change the names of registry keys, use the New-Item and Rename-Item cmdlet. -To change the names and data in registry values, use the New-ItemProperty, Set-ItemProperty, and Rename-ItemProperty cmdlets. + `Set-Item` is not supported by the PowerShell FileSystem provider. +To change the values of items in the file system, use the `Set-Content` cmdlet. - **Set-Item** is designed to work with the data exposed by any provider. +In the Registry drives, HKLM: and HKCU:, `Set-Item` changes the data in the (Default) value of a registry key. +To create and change the names of registry keys, use the `New-Item` and `Rename-Item` cmdlet. +To change the names and data in registry values, use the `New-ItemProperty`, `Set-ItemProperty`, and `Rename-ItemProperty` cmdlets. + +`Set-Item` is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. -* - ## RELATED LINKS [Clear-Item](Clear-Item.md) @@ -321,4 +324,6 @@ For more information, see about_Providers. [Remove-Item](Remove-Item.md) -[Rename-Item](Rename-Item.md) \ No newline at end of file +[Rename-Item](Rename-Item.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Set-ItemProperty.md b/reference/6/Microsoft.PowerShell.Management/Set-ItemProperty.md index 75904cf065d6..7f7732140ea5 100644 --- a/reference/6/Microsoft.PowerShell.Management/Set-ItemProperty.md +++ b/reference/6/Microsoft.PowerShell.Management/Set-ItemProperty.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821631 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Set-ItemProperty --- - # Set-ItemProperty ## SYNOPSIS + Creates or changes the value of a property of an item. ## SYNTAX ### propertyValuePathSet (Default) + ``` Set-ItemProperty [-Path] [-Name] [-Value] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -23,6 +24,7 @@ Set-ItemProperty [-Path] [-Name] [-Value] [-PassThr ``` ### propertyPSObjectPathSet + ``` Set-ItemProperty [-Path] -InputObject [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -30,6 +32,7 @@ Set-ItemProperty [-Path] -InputObject [-PassThru] [-Force] ``` ### propertyValueLiteralPathSet + ``` Set-ItemProperty -LiteralPath [-Name] [-Value] [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -37,6 +40,7 @@ Set-ItemProperty -LiteralPath [-Name] [-Value] [-Pa ``` ### propertyPSObjectLiteralPathSet + ``` Set-ItemProperty -LiteralPath -InputObject [-PassThru] [-Force] [-Filter ] [-Include ] [-Exclude ] [-Credential ] @@ -45,34 +49,58 @@ Set-ItemProperty -LiteralPath -InputObject [-PassThru] [-F ``` ## DESCRIPTION -The **Set-ItemProperty** cmdlet changes the value of the property of the specified item. + +The `Set-ItemProperty` cmdlet changes the value of the property of the specified item. You can use the cmdlet to establish or change the properties of items. -For example, you can use **Set-ItemProperty** to set the value of the **IsReadOnly** property of a file object to $True. +For example, you can use `Set-ItemProperty` to set the value of the **IsReadOnly** property of a file object to `$True`. -You also use **Set-ItemProperty** to create and change registry values and data. +You also use `Set-ItemProperty` to create and change registry values and data. For example, you can add a new registry entry to a key and establish or change its value. ## EXAMPLES ### Example 1: Set a property of a file -```powershell -Set-ItemProperty -Path C:\GroupFiles\final.doc -Name IsReadOnly -Value $true -``` -This command sets the value of the **IsReadOnly** property of the final.doc file to true. +This command sets the value of the **IsReadOnly** property of the "final.doc" file to "true". It uses **Path** to specify the file, **Name** to specify the name of the property, and the **Value** parameter to specify the new value. The file is a **System.IO.FileInfo** object and **IsReadOnly** is just one of its properties. To see all of the properties, type `Get-Item C:\GroupFiles\final.doc | Get-Member -MemberType Property`. -The `$true` automatic variable represents a value of TRUE. +The `$true` automatic variable represents a value of "TRUE". For more information, see [about_Automatic_Variables](../Microsoft.PowerShell.Core/About/about_Automatic_Variables.md). +```powershell +Set-ItemProperty -Path C:\GroupFiles\final.doc -Name IsReadOnly -Value $true +``` + ### Example 2: Create a registry entry and value + +This example shows how to use `Set-ItemProperty` to create a new registry entry and to assign a value to the entry. +It creates the "NoOfEmployees" entry in the "ContosoCompany" key in "HKLM\Software" key and sets its value to 823. + +Because registry entries are considered to be properties of the registry keys, which are items, you use `Set-ItemProperty` to create registry entries, and to establish and change their values. + +The first command creates the registry entry. +It uses **Path** to specify the path of the `HKLM:` drive and the "Software\MyCompany" key. +The command uses **Name** to specify the entry name and **Value** to specify a value. + +The second command uses the `Get-ItemProperty` cmdlet to see the new registry entry. +If you use the `Get-Item` or `Get-ChildItem` cmdlets, the entries do not appear because they are properties of a key, not items or child items. + +The third command changes the value of the **NoOfEmployees** entry to 824. + +You can also use the `New-ItemProperty` cmdlet to create the registry entry and its value and then use `Set-ItemProperty` to change the value. + +For more information about the `HKLM:` drive, type `Get-Help Get-PSDrive`. +For more information about how to use PowerShell to manage the registry, type `Get-Help Registry`. + +```powershell +Set-ItemProperty -Path "HKLM:\Software\ContosoCompany" -Name "NoOfEmployees" -Value 823 +Get-ItemProperty -Path "HKLM:\Software\ContosoCompany" ``` -PS C:\> Set-ItemProperty -Path "HKLM:\Software\ContosoCompany" -Name "NoOfEmployees" -Value 823 -PS C:\> Get-ItemProperty -Path "HKLM:\Software\ContosoCompany" +```output PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\contosocompany PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software PSChildName : contosocompany @@ -81,9 +109,14 @@ PSProvider : Microsoft.PowerShell.Core\Registry NoOfLocations : 2 NoOfEmployees : 823 -PS C:\> Set-ItemProperty -Path "HKLM:\Software\ContosoCompany" -Name "NoOfEmployees" -value 824 -PS C:\> Get-ItemProperty -Path "HKLM:\Software\ContosoCompany" +``` + +```powershell +Set-ItemProperty -Path "HKLM:\Software\ContosoCompany" -Name "NoOfEmployees" -Value 824 +Get-ItemProperty -Path "HKLM:\Software\ContosoCompany" +``` +```output PSPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\contosocompany PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software PSChildName : contosocompany @@ -93,48 +126,32 @@ NoOfLocations : 2 NoOfEmployees : 824 ``` -This example shows how to use **Set-ItemProperty** to create a new registry entry and to assign a value to the entry. -It creates the **NoOfEmployees** entry in the ContosoCompany key in HKLM\Software key and sets its value to 823. - -Because registry entries are considered to be properties of the registry keys, which are items, you use **Set-ItemProperty** to create registry entries, and to establish and change their values. - -The first command creates the registry entry. -It uses *Path* to specify the path of the HKLM: drive and the Software\MyCompany key. -The command uses *Name* to specify the entry name and *Value* to specify a value. +### Example 3: Modify an item by using the pipeline -The second command uses the Get-ItemProperty cmdlet to see the new registry entry. -If you use the Get-Item or Get-ChildItem cmdlets, the entries do not appear because they are properties of a key, not items or child items. +These commands show how to use a pipeline operator (`|`) to send an item to `Set-ItemProperty`. -The third command changes the value of the **NoOfEmployees** entry to 824. +The first part of the command uses `Get-ChildItem` to get an object that represents the "Weekly.txt" file. +The command uses a pipeline operator to send the file object to `Set-ItemProperty`. +The `Set-ItemProperty` command uses the **Name** and **Value** parameters to specify the property and its new value. -You can also use the New-ItemProperty cmdlet to create the registry entry and its value and then use **Set-ItemProperty** to change the value. +This command is equivalent to using the **InputObject** parameter to specify the object that `Get-ChildItem` gets. -For more information about the HKLM: drive, type `Get-Help Get-PSDrive`. -For more information about how to use PowerShell to manage the registry, type `Get-Help Registry`. - -### Example 3: Modify an item by using the pipeline -``` -PS C:\> Get-ChildItem weekly.txt | Set-ItemProperty -Name IsReadOnly -Value $True +```powershell +Get-ChildItem weekly.txt | Set-ItemProperty -Name IsReadOnly -Value $True ``` -These commands show how to use a pipeline operator (|) to send an item to **Set-ItemProperty**. - -The first part of the command uses **Get-ChildItem** to get an object that represents the Weekly.txt file. -The command uses a pipeline operator to send the file object to **Set-ItemProperty**. -The **Set-ItemProperty** command uses the *Name* and *Value* parameters to specify the property and its new value. - -This command is equivalent to using the *InputObject* parameter to specify the object that **Get-ChildItem** gets. - ## PARAMETERS ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, this cmdlet prompts you for a password. +Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. +If you type a user name, you are prompted for a password. -This parameter is not supported by any providers installed with parameter is not supported by any providers installed with PowerShell. +> [!WARNING] +> This parameter is not supported by any providers installed with Windows PowerShell. ```yaml Type: PSCredential @@ -143,13 +160,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -Exclude + Specifies those items upon which the cmdlet does not act, and includes all others. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -164,10 +185,12 @@ Accept wildcard characters: False ``` ### -Filter + Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. + The syntax of the filter, including the use of wildcard characters, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when it retrieves the objects instead of having PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String @@ -178,13 +201,14 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force + Forces the cmdlet to set a property on items that cannot otherwise be accessed by the user. Implementation varies from provider to provider. -For more information, see about_Providers. +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ```yaml Type: SwitchParameter @@ -193,13 +217,17 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Include + Specifies only those items upon which the cmdlet acts, which excludes all others. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcard characters are permitted. ```yaml Type: String[] @@ -214,6 +242,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the object that has the properties that this cmdlet changes. Enter a variable that contains the object or a command that gets the object. @@ -230,9 +259,10 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies a path of the item property. -The value of *LiteralPath* is used exactly as it is typed. -No characters are interpreted as wildcard characters. +Unlike the **Path** parameter, the value of **LiteralPath** is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -249,6 +279,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the property. ```yaml @@ -264,6 +295,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object that represents the item property. By default, this cmdlet does not generate any output. @@ -280,6 +312,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path of the items with the property to modify. ```yaml @@ -295,6 +328,7 @@ Accept wildcard characters: False ``` ### -Value + Specifies the value of the property. ```yaml @@ -310,6 +344,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -325,6 +360,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -340,43 +376,26 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: usetx - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.Management.Automation.PSObject + You can pipe objects to this cmdlet. ## OUTPUTS ### None, System.Management.Automation.PSCustomObject + This cmdlet generates a **PSCustomObject** object that represents the item that was changed and its new property value, if you specify the *PassThru* parameter. Otherwise, this cmdlet does not generate any output. ## NOTES -* **Set-ItemProperty** is designed to work with the data exposed by any provider. To list the providers available in your session, type **Get-PSProvider**. For more information, see about_Providers. -* +- `Set-ItemProperty` is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. For more information, see about_Providers. ## RELATED LINKS @@ -392,4 +411,6 @@ Otherwise, this cmdlet does not generate any output. [Remove-ItemProperty](Remove-ItemProperty.md) -[Rename-ItemProperty](Rename-ItemProperty.md) \ No newline at end of file +[Rename-ItemProperty](Rename-ItemProperty.md) + +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Management/Test-Path.md b/reference/6/Microsoft.PowerShell.Management/Test-Path.md index 08ceb98e2132..a47d2729b8c5 100644 --- a/reference/6/Microsoft.PowerShell.Management/Test-Path.md +++ b/reference/6/Microsoft.PowerShell.Management/Test-Path.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 10/18/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821647 external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml title: Test-Path --- - # Test-Path ## SYNOPSIS + Determines whether all elements of a path exist. ## SYNTAX ### Path (Default) + ``` Test-Path [-Path] [-Filter ] [-Include ] [-Exclude ] [-PathType ] [-IsValid] [-Credential ] @@ -23,6 +24,7 @@ Test-Path [-Path] [-Filter ] [-Include ] [-Exclude ``` ### LiteralPath + ``` Test-Path -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-PathType ] [-IsValid] [-Credential ] @@ -30,79 +32,115 @@ Test-Path -LiteralPath [-Filter ] [-Include ] [-Exc ``` ## DESCRIPTION -The **Test-Path** cmdlet determines whether all elements of the path exist. -It returns $True if all elements exist and $False if any are missing. + +The `Test-Path` cmdlet determines whether all elements of the path exist. +It returns `$True` if all elements exist and `$False` if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal or leaf element. ## EXAMPLES ### Example 1: Test a path + ``` PS C:\> Test-Path -Path "C:\Documents and Settings\DavidC" +True ``` This command checks whether all elements in the path exist, that is, the C: directory, the Documents and Settings directory, and the DavidC directory. -If any are missing, the cmdlet returns $False. -Otherwise, it returns $True. +If any are missing, the cmdlet returns `$False`. +Otherwise, it returns `$True`. ### Example 2: Test the path of a profile + ``` PS C:\> Test-Path -Path $profile +False PS C:\> Test-Path -Path $profile -IsValid +True ``` These commands test the path of the PowerShell profile. The first command determines whether all elements in the path exist. The second command determines whether the syntax of the path is correct. -In this case, the path is $False, but the syntax is correct ($True). -These commands use $profile, the automatic variable that points to the location for the profile, even if the profile does not exist. +In this case, the path is `$False`, but the syntax is correct `$True`. +These commands use `$profile`, the automatic variable that points to the location for the profile, even if the profile does not exist. For more information about automatic variables, see about_Automatic_Variables. ### Example 3: Check whether there are any files besides a specified type + ``` PS C:\> Test-Path -Path "C:\CAD\Commercial Buildings\*" -Exclude *.dwg +False ``` This command checks whether there are any files in the Commercial Buildings directory other than .dwg files. -The command uses the *Path* parameter to specify the path. +The command uses the **Path** parameter to specify the path. Because the path includes a space, the path is enclosed in quotation marks. The asterisk at the end of the path indicates the contents of the Commercial Building directory. With long paths, such as this one, type the first few letters of the path, and then use the TAB key to complete the path. -The command specifies the *Exclude* parameter to specify files that will be omitted from the evaluation. +The command specifies the **Exclude** parameter to specify files that will be omitted from the evaluation. -In this case, because the directory contains only .dwg files, the result is $False. +In this case, because the directory contains only .dwg files, the result is `$False`. ### Example 4: Check for a file + ``` PS C:\> Test-Path -Path $profile -PathType leaf +True ``` -This command checks whether the path stored in the $profile variable leads to a file. -In this case, because the PowerShell profile is a .ps1 file, the cmdlet returns $True. +This command checks whether the path stored in the `$profile` variable leads to a file. +In this case, because the PowerShell profile is a .ps1 file, the cmdlet returns `$True`. ### Example 5: Check paths in the Registry + +These commands use `Test-Path` with the PowerShell registry provider. + +The first command tests whether the registry path of the **Microsoft.PowerShell** registry key is correct on the system. +If PowerShell is installed correctly, the cmdlet returns `$True`. + +> [!IMPORTANT] +> `Test-Path` does not work correctly with all PowerShell providers. +> For example, you can use `Test-Path` to test the path of a registry key, but if you use it to test the path of a registry entry, it always returns `$False`, even if the registry entry is present. + +```powershell +Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell" ``` -PS C:\> Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell" + +```output True -PS C:\> Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy" +``` + +```powershell +Test-Path -Path "HKLM:\Software\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell\ExecutionPolicy" +``` + +```output False ``` -These commands use **Test-Path** with the PowerShell registry provider. +### Example 6: Test if a file is newer than a specified date + +This command uses the **NewerThan** dynamic parameter to determine whether the "PowerShell.exe" file on the computer is newer than "July 13, 2009". + +The NewerThan parameter works only in file system drives. -The first command tests whether the registry path of the Microsoft.PowerShell registry key is correct on the system. -If PowerShell is installed correctly, the cmdlet returns $True. +```powershell +Test-Path $pshome\PowerShell.exe -NewerThan "July 13, 2009" +``` -**Test-Path** does not work correctly with all PowerShell providers. -For example, you can use **Test-Path** to test the path of a registry key, but if you use it to test the path of a registry entry, it always returns $False, even if the registry entry is present. +```output +True +``` ## PARAMETERS ### -OlderThan + Specify a time as a **DateTime** object. ```yaml @@ -118,6 +156,7 @@ Accept wildcard characters: False ``` ### -NewerThan + Specify a time as a **DateTime** object. ```yaml @@ -133,11 +172,12 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as User01 or Domain01\User01. -Or, enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. +Or, enter a **PSCredential** object, such as one generated by the `Get-Credential` cmdlet. If you type a user name, this cmdlet prompts you for a password. This parameter is not supported by any providers installed with PowerShell. @@ -155,8 +195,9 @@ Accept wildcard characters: False ``` ### -Exclude + Specifies items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. @@ -173,8 +214,9 @@ Accept wildcard characters: False ``` ### -Filter + Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. The syntax of the filter, including the use of wildcard characters, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when it retrieves the objects instead of having PowerShell filter the objects after they are retrieved. @@ -191,8 +233,9 @@ Accept wildcard characters: False ``` ### -Include + Specifies paths that this cmdlet tests. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". Wildcard characters are permitted. @@ -209,8 +252,9 @@ Accept wildcard characters: False ``` ### -IsValid + Indicates that this cmdlet tests the syntax of the path, regardless of whether the elements of the path exist. -This cmdlet returns $True if the path syntax is valid and $False if it is not. +This cmdlet returns `$True` if the path syntax is valid and `$False` if it is not. ```yaml Type: SwitchParameter @@ -225,8 +269,9 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies a path to be tested. -Unlike *Path*, the value of the *LiteralPath* parameter is used exactly as it is typed. +Unlike **Path**, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcard characters. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -244,6 +289,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies a path to be tested. Wildcard characters are permitted. If the path includes spaces, enclose it in quotation marks. @@ -261,16 +307,18 @@ Accept wildcard characters: False ``` ### -PathType + Specifies the type of the final element in the path. -This cmdlet returns $True if the element is of the specified type and $False if it is not. +This cmdlet returns `$True` if the element is of the specified type and `$False` if it is not. The acceptable values for this parameter are: - Container. -An element that contains other elements, such as a directory or registry key. + An element that contains other elements, such as a directory or registry key. - Leaf. -An element that does not contain other elements, such as a file. + An element that does not contain other elements, such as a file. - Any. -Either a container or a leaf. + Either a container or a leaf. + Tells whether the final element in the path is of a particular type. ```yaml @@ -287,6 +335,7 @@ Accept wildcard characters: False ``` ### -UseTransaction + Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see Includes the command in the active transaction. @@ -306,28 +355,28 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS ### System.String + You can pipe a string that contains a path, but not a literal path, to this cmdlet. ## OUTPUTS ### System.Boolean + The cmdlet returns a **Boolean** value. ## NOTES -* The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path names and return the names in a concise format that all PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path manipulators. - You can use the **Path** cmdlets with several providers, including the FileSystem, Registry, and Certificate providers. +The cmdlets that contain the **Path** noun (the **Path** cmdlets) work with path names and return the names in a concise format that all PowerShell providers can interpret. They are designed for use in programs and scripts where you want to display all or part of a path name in a particular format. Use them as you would use **Dirname**, **Normpath**, **Realpath**, **Join**, or other path manipulators. - **Test-Path** is designed to work with the data exposed by any provider. +The `Test-Path` is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PSProvider`. -For more information, see about_Providers. - -* +For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Security/Providers/Certificate-Provider.md b/reference/6/Microsoft.PowerShell.Security/Providers/Certificate-Provider.md deleted file mode 100644 index bfac3b1b2094..000000000000 --- a/reference/6/Microsoft.PowerShell.Security/Providers/Certificate-Provider.md +++ /dev/null @@ -1,370 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Certificate Provider -online version: http://go.microsoft.com/fwlink/?LinkId=834968 ---- -# Certificate Provider - -## Provider name - -Certificate - -## Drives - -Cert: - -## Short description - -Provides access to X.509 certificate stores and certificates in PowerShell. - -## Detailed description - -The PowerShell Certificate provider lets you navigate the certificate namespace and view the certificate stores and certificates. It also lets you open the Certificates snap-in for the Microsoft Management Console (MMC). - -> [!NOTE] -> Beginning in Windows PowerShell 3.0, the Microsoft.PowerShell.Security module that contains the [Certificate Provider](Certificate-Provider.md) is not imported automatically into every session. To use the Cert: > drive, use the [Import-Module](../../Microsoft.PowerShell.Core/Import-Module.md) cmdlet to import the module, or run a command that uses the Cert: drive, such as a `Set-Location Cert:` command. - -Beginning in Windows PowerShell 3.0, the Certificate provider enhances its support for managing Secure Socket Layer (SSL) certificates for web hosting by adding support for cmdlets and new dynamic parameters that create and delete certificate stores in the LocalMachine certificate store location, and find, move, and delete certificates. - -New dynamic parameters, `DnsName`, `EKU`, `SSLServerAuthentication`, and `ExpiringInDays` have been added to the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet in the Cert: drive. Also, a `DeleteKey` dynamic parameter has been added to [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) in the Cert: drive. The new dynamic parameters are available in the Windows PowerShell 3.0 and newer Windows PowerShell releases, and work with IIS 8.0, available on Windows Server 2012 and later releases of the Windows Server operating system. - -New script properties, `DnsNameList`, `EnhancedKeyUsageList`, and `SendAsTrustedIssuer`, have been added to the x509Certificate2 object that represents the certificates to make it easy to search and manage the certificates. - -These new features let you search for certificates based on their DNS names and expiration dates, and distinguish client and server authentication certificates by the value of their Enhanced Key Usage (EKU) properties. - -These enhancements are designed to support the WebHosting certificate store created by IIS. This certificate store is optimized to scale for efficient, automated management of the thousands of certificates that are required for dynamic shared hosting. The WebHosting certificate store is available starting in IIS 8.0, available with Web Server (IIS) on Windows Server 2012 and later releases of the Windows Server operating system. - -To populate the `DnsNameList` property, the Certificate provider copies the content from the DNSName entry in the SubjectAlternativeName (SAN) extension. If the SAN extension is empty, the property is populated with content from the Subject field of the certificate. - -To populate the `EnhancedKeyUsageList` property, the Certificate provider copies the OID properties of the EnhancedKeyUsage (EKU) field in the certificate and creates a friendly name for it.. - -The Certificate provider exposes the certificate namespace as the Cert: drive in PowerShell. The Cert: drive has the following three levels: - -- Store locations (Microsoft.PowerShell.Commands.X509StoreLocation), which are high-level containers that group the certificates for the current user and for all users. Each system has a CurrentUser and LocalMachine (all users) store location. - -- Certificates stores (System.Security.Cryptography.X509Certificates.X509Store), which are physical stores in which certificates are saved and managed. - -- X.509 certificates (System.Security.Cryptography.X509Certificates.X509Certificate2), each of which represent an X.509 certificate on the computer. Certificates are identified by their thumbprints. - -In Windows PowerShell 3.0, the Certificate provider supports the [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md), [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md), [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md), [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md), [New-Item](../../Microsoft.PowerShell.Management/New-Item.md), and [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) cmdlets. - -In Windows PowerShell 2.0, the Certificate provider supports the [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md), [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md), [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md), [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md), and [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) cmdlets. - -In addition, PowerShell Security module (Microsoft.PowerShell.Security), which includes the Certificate provider, also includes cmdlets to get and set Authenticode signatures and to get certificates. For a list of cmdlets in the Security module, type `Get-Command -Module *security`. - -## CAPABILITIES - -ShouldProcess - -## EXAMPLES - -### Navigating the Cert: Drive - -#### Example 1: Navigating to the root of the Cert: Drive - -This command uses the `Set-Location` command to change the current location to the Root certificate store in the LocalMachine store location. Use a backslash (\\) or a forward slash (/) to indicate a level of the Cert: drive. - -```powershell -Set-Location -Path LocalMachine\Root - -``` - -If you are not in the Cert: drive, begin the path with the drive name. - -### Displaying the Contents of the Cert: Drive - -#### Example 1: Displaying the Contents of the Cert: Drive - -This command uses the `Get-ChildItem` cmdlet to display the certificate stores in the CurrentUser certificate store location. - -```powershell -Get-ChildItem -Path cert:\CurrentUser - -``` - -If you are in the Cert: drive, you can omit the drive name. - -### Example 2: Displaying certificate properties within the Cert: Drive - -This command gets a certificate and displays all of its properties. It uses the `Get-ChildItem` cmdlet to get the certificate and the Property parameter of `Format-List` with a wildcard character (*) to display all of the properties of the certificate. - -The certificate is identified by its thumbprint. - -```powershell -Get-ChildItem -Path cert:\LocalMachine\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B | Format-List -Property * - -``` - -#### Example 3: Use the Recurse parameter with Format-Table to view all certificate properties - -This command displays the web hosting properties of all certificates in the LocalMachine certificate store location. - -It uses the Recurse parameter of the `Get-ChildItem` cmdlet to get all certificates in all stores of the LocalMachine store location. A pipeline operator sends the certificates to the `Format-Table` command, which displays the selected properties of each certificate in a table. - -```powershell -Get-ChildItem -Path cert:\LocalMachine -Recurse | Format-Table -Property DnsNameList, EnhancedKeyUsageList, NotAfter, SendAsTrustedIssuer - -``` - -### Opening the Certificates MMC Snap-in - -#### Example 1: Opening the Certificates MMC Snap-in - -This command opens the Certificates MMC snap-in to manage the specified certificate. - -```powershell -Invoke-Item cert:\CurrentUser\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B - -``` - -### Getting Selected Certificates - -#### Example 1: Find all CodeSigning certificates using the CodeSigning cert parameter - -This command uses the CodeSigningCert and Recurse parameters of the `Get-ChildItem` cmdlet to get all of the certificates on the computer that have code-signing authority. - -```powershell -Get-ChildItem -Path cert: -CodeSigningCert -Recurse - -``` - -#### Example 2: Find expired certificates - -This command uses the ExpiringInDays parameter of the `Get-ChildItem` cmdlet to get certificates that will expire within the next 30 days. - -```powershell -Get-ChildItem -Path cert:\LocalMachine\WebHosting -ExpiringInDays 30 - -``` - -#### Example 3: Find Server SSL Certificates using the SSLServerAuthentication parameter - -This command uses the SSLServerAuthentication parameter of the `Get-ChildItem` cmdlet to get all - -Server SSL Certificates in the My and WebHosting stores. - -```powershell -Get-ChildItem -Path cert:\LocalMachine\My, cert:\LocalMachine\WebHosting -SSLServerAuthentication - -``` - -#### Example 4: Find expired certificates on remote computers - -This command uses the `Invoke-Command` cmdlet to run a `Get-ChildItem` command on the Srv01 and Srv02 computers. A value of zero (0) in the ExpiringInDays parameter gets certificates on the Srv01 and Srv02 computers that have expired. - -```powershell -Invoke-Command -ComputerName Srv01, Srv02 {Get-ChildItem -Path cert:\* -Recurse -ExpiringInDays 0} - -``` - -#### Example 5: Combining filters to find a specific set of certificates - -This command gets all certificates in the LocalMachine store location that have "fabrikam" in their DNS name, "Client Authentication" in their EKU, a value of `$true` for the SendAsTrustedIssuer property, and do not expire within the next 30 days. - -```powershell -Get-ChildItem -Path cert:\* -Recurse -DNSName "*fabrikam*" -EKU "*Client Authentication*" | Where-Object {$_.SendAsTrustedIssuer -and $_.NotAfter -gt (get-date).AddDays.(30)} - -``` - -The NotAfter property stores the certificate expiration date. - -### Moving Certificates - -#### Example 1: Move all SSL Server authentication certs to the WebHosting store - -This command uses the `Move-Item` cmdlet to move a certificate from the My store to the WebHosting store. - -`Move-Item` will not move certificate stores and it will not move certificates to a different store location, such as moving a certificate from LocalMachine to CurrentUser. Also, `Move-Item` moves certificates, but it does not move private keys. - -```powershell -Move-Item -Path cert:\LocalMachine\My\5DDC44652E62BF9AA1116DC41DE44AB47C87BDD0 -Destination cert:\LocalMachine\WebHosting - -``` - -### Deleting Certificates and Private Keys - -#### Example 1: Delete a certificate from the CA store - -This command uses the SSLServerAuthentication parameter of the `Get-ChildItem` cmdlet to get SSL server authentication certificates in the MY certificate store. - -It uses a pipeline operator to send the certificates to the `Move-Item` cmdlet, which moves the certificates to the WebHosting store. - -```powershell -Get-ChildItem -Path cert:\LocalMachine\My -SSLServerAuthentication | Move-Item -Destination cert:\LocalMachine\WebHosting - -``` - -#### Example 2: Delete a certificate from a remote computer - -This command deletes a certificate from the CA certificate store, but leaves the associated private key intact. - -In the Cert: drive, the `Remove-Item` cmdlet supports only the DeleteKey, Path, WhatIf, and Confirm parameters. All other parameters are ignored. - -```powershell -Remove-Item -Path cert:\LocalMachine\CA\5DDC44652E62BF9AA1116DC41DE44AB47C87BDD0 - -``` - -#### Example 3: Delete private keys from a remote computer using credential delegation - -This series of commands enables delegation and then deletes the certificate and associated private key on a remote computer. To delete a private key on a remote computer, you must use delegated credentials. - -```powershell -# Use the Enagle-WSManCredSSP cmdlet to enable Credential Security Service Provider (CredSSP) authentication on a client on the S1 remote computer. -# CredSSP permits delegated authentication. -Enable-WSManCredSSP -Role Client -DelegateComputer S1 -# Use the Connect-WSMan cmdlet to connect the S1 computer to the WinRM service on the local computer. -# When this command completes, the S1 computer appears in the local WSMan: drive in PowerShell. -Connect-WSMan -ComputerName S1 -Credential Domain01\Admin01 -# Now, you can use the Set-Item cmdlet in the WSMan: drive to enable the CredSSP attribute for the WinRM service. -Set-Item -Path WSMan:\S1\Service\Auth\CredSSP -Value $true -# Start a remote session on the s1 computer using the New-PSSession cmdlet, and specify CredSSP authentication. -# Saves the session in the $s variable. -$s = New-PSSession S1 -Authentication CredSSP -Credential Domain01\Admin01 -# Finally, use the Invoke-Command cmdlet to run a Remove-Item command in the session in the $s variable. -# The Remove-Item command uses the DeleteKey parameter to remove the private key along with the specified certificate. -Invoke-Command -Session $s { Remove-Item cert:\LocalMachine\My\D2D38EBA60CAA1C12055A2E1C83B15AD450110C2 -DeleteKey } -``` - -#### Example 4: Delete certs using wildcards in a DNS name - -This command uses the ExpiringInDays parameter of the `Get-ChildItem` cmdlet with a value of 0 to get certificates in the WebHosting store that have expired. - -It uses a pipeline operator to pass the certificates to the `Remove-Item` cmdlet, which deletes them. The command uses the DeleteKey parameter to delete the private key along with the certificate. - -```powershell -Get-ChildItem -Path cert:\LocalMachine\WebHosting -ExpiringInDays 0 | Remove-Item -DeleteKey - -``` - -### Creating Certificate Stores - -#### Example 1: Create a new certificate store - -This command creates a new certificate store named "CustomStore" in the LocalMachine store location. - -In the Cert: drive, the `New-Item` cmdlet creates certificate stores in the LocalMachine store location. It supports the Name, Path, WhatIf, and Confirm parameters. All other parameters are ignored. - -```powershell -New-Item -Path cert:\LocalMachine\CustomStore - -``` - -The command returns a System.Security.Cryptography.X509Certificates.X509Store that represents the new certificate store. - -#### Example 2: Create a new certificate store on a remote computer - -This command creates a new certificate store named "HostingStore" in the LocalMachine store location on the Server01 computer. - -The command uses the `Invoke-Command` cmdlet to run a `New-Item` command on the Server01 computer. - -```powershell -Invoke-Command -ComputerName Server01 { New-Item -Path cert:\LocalMachine\CustomStore } - -``` - -The command returns a System.Security.Cryptography.X509Certificates.X509Store that represents the new certificate store. - -### Deleting Certificate Stores - -#### Example 1: Delete a certificate store and all contained certificates, from a remote computer - -This command uses the `Invoke-Command` cmdlet to run a `Remove-Item` command on the S1 and S2 computers. The `Remove-Item` command includes the Recurse parameter, which deletes the certificates in the store before it deletes the store. - -```powershell -Invoke-Command -ComputerName S1, S2 { Remove-Item -Path cert:\LocalMachine\TestStore -Recurse} - -``` - -## 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. - -### CodeSigningCert - -Gets only those certificates with code-signing authority. - -This parameter gets certificates that have "Code Signing" in their EnhancedKeyUsageList property value. Because certificates that have an empty EnhancedKeyUsageList can be used for all purposes, searches for code signing certificates also return certificates that have an empty `EnhancedKeyUsageList` property value. - -This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - -#### Cmdlets supported - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - -### DnsName - -Gets certificates that have the specified domain name or name pattern in the `DNSNameList` property of the certificate. - -The value of this parameter can either be Unicode or ASCII. Punycode values are converted to Unicode. Wildcard characters (*) are permitted. This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - -This parameter was introduced in Windows PowerShell 3.0. - -#### Cmdlets supported - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - -### EKU - -Gets certificates that have the specified text or text pattern in the `EnhancedKeyUsageList` property of the certificate. Wildcard characters (*) are permitted. The `EnhancedKeyUsageList` property contains the friendly name and the OID fields of the EKU. - -Because certificates that have an empty EnhancedKeyUsageList can be used for all purposes, all EKU searches return certificates that have an empty `EnhancedKeyUsageList` property value. This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - -This parameter was introduced in Windows PowerShell 3.0. - -#### Cmdlets supported - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - -### ExpiringInDays - -Gets certificates that are expiring in or before the specified number of days. Enter an integer. A value of 0 (zero) gets certificates that have expired. This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - -This parameter was introduced in Windows PowerShell 3.0. - -#### Cmdlets supported - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - -### SSLServerAuthentication - -Gets only server certificates for SSL web hosting. This parameter gets certificates that have "Server Authentication" in their `EnhancedKeyUsageList` property value. Because certificates that have an empty EnhancedKeyUsageList can be used for all purposes, SSLServerAuthentication searches also return certificates that have an empty `EnhancedKeyUsageList` property value. - -This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - -This parameter was introduced in Windows PowerShell 3.0. - -#### Cmdlets supported - -- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - -### DeleteKey - -Deletes the associated private key when it deletes the certificate. - -To delete a private key that is associated with a user certificate in the Cert:\CurrentUser store on a remote computer, you must use delegated credentials. When using the [Invoke-Command](../../Microsoft.PowerShell.Core/Invoke-Command.md) cmdlet to run a [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) command remotely, after considering the security risks, use the CredSSP parameter to enable delegation. - -This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - -This parameter was introduced in Windows PowerShell 3.0. - -#### Cmdlets supported - -- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - -## See also - -[about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) - -[about_Signing](../../Microsoft.PowerShell.Core/About/about_Signing.md) - -[Get-AuthenticodeSignature](../Get-AuthenticodeSignature.md) - -[Set-AuthenticodeSignature](../Set-AuthenticodeSignature.md) - -[Get-PfxCertificate](../Get-PfxCertificate.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider.md b/reference/6/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider.md new file mode 100644 index 000000000000..edddd095bacf --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Security/Providers/about_Certificate_Provider.md @@ -0,0 +1,557 @@ +--- +ms.date: 10/18/2018 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: Certificate Provider +online version: http://go.microsoft.com/fwlink/?LinkId=834968 +--- +# Certificate Provider + +## Provider name + +Certificate + +## Drives + +`Cert:` + +## Capabilities + +**ShouldProcess** + +## Short description + +Provides access to X.509 certificate stores and certificates in PowerShell. + +## Detailed description + +The PowerShell **Certificate** provider lets you get, add, change, clear, and delete +certificates and certificate stores in PowerShell. + +Certificates are {{Fill in description}} + +The **Certificate** drive is a hierarchical namespace containing the cerificate stores and certificates on your computer. + +The **Certificate** provider supports the following cmdlets, which are covered +in this article. + +- [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md) +- [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) +- [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) +- [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) +- [Get-ItemProperty](../../Microsoft.PowerShell.Management/Get-ItemProperty.md) +- [Set-ItemProperty](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) +- [Clear-ItemProperty](../../Microsoft.PowerShell.Management/Set-ItemProperty.md) +- [Get-AuthenticodeSignature](../Get-AuthenticodeSignature.md) +- [Set-AuthenticodeSignature](../Set-AuthenticodeSignature.md) + +{{Make sure list is correct}} + +## Types exposed by this provider + +The Certificate drive exposes the following types. + +- Store locations (Microsoft.PowerShell.Commands.X509StoreLocation), which are + high-level containers that group the certificates for the current user and + for all users. Each system has a CurrentUser and LocalMachine (all users) + store location. + +- Certificates stores (System.Security.Cryptography.X509Certificates.X509Store), which are physical stores in which certificates are saved and managed. + +- X.509 **System.Security.Cryptography.X509Certificates.X509Certificate2** + certificates, each of which represent an X.509 certificate on the computer. + Certificates are identified by their thumbprints. + +## Navigating the Certificate drive + +The **Certificate** provider exposes the certificate namespace as the `Cert:` +drive in PowerShell. This command uses the `Set-Location` command to change the +current location to the Root certificate store in the LocalMachine store +location. Use a backslash (\\) or a forward slash (/) to indicate a level of +the `Cert:` drive. + +```powershell +Set-Location Cert: +``` + +You can also work with the certificate provider from any other PowerShell +drive. To reference an alias from another location, use the `Cert:` drive name +in the path. + +```powershell +PS Cert:\> Set-Location -Path LocalMachine\Root +``` + +To return to a file system drive, type the drive name. For example, type: + +```powershell +Set-Location C: +``` + +> [!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](../../Microsoft.PowerShell.Management/Get-ChildItem.md), +> `cd` is an alias for [Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md). and `pwd` is +> an alias for [Get-Location](../../Microsoft.PowerShell.Management/Get-Location.md). + +## Displaying the Contents of the Cert: drive + +New dynamic parameters, `DnsName`, `EKU`, `SSLServerAuthentication`, and +`ExpiringInDays` have been added to the `Get-ChildItem` cmdlet in the `Cert:` +drive. The new dynamic parameters are available in the Windows PowerShell 3.0 +and newer PowerShell releases. The provider parameters work with IIS 8.0 +on Windows Server 2012 and later. + +This command uses the `Get-ChildItem` cmdlet to display the certificate stores +in the CurrentUser certificate store location. + +If you are not in the `Cert:` drive, use an absolute path. + +```powershell +PS Cert:\CurrentUser\> Get-ChildItem +``` + +### Displaying certificate properties within the Cert: drive + +This example gets a certificate with `Get-Item` and stores it in a variable. +The example shows the new certificate script properties (**DnsNameList**, +**EnhancedKeyUsageList**, **SendAsTrustedIssuer**) using `Select-Object`. + +```powershell +$c = Get-Item cert:\LocalMachine\My\52A149D0393CE8A8D4AF0B172ED667A9E3A1F44E +$c | Format-List DnsNameList, EnhancedKeyUsageList, SendAsTrustedIssuer +``` + +```output +DnsNameList : {SERVER01.contoso.com} +EnhancedKeyUsageList : {WiFi-Machine (1.3.6.1.4.1.311.42.2.6), + Client Authentication (1.3.6.1.5.5.7.3.2)} +SendAsTrustedIssuer : False +``` + +### Find all CodeSigning certificates + +This command uses the **CodeSigningCert** and **Recurse** parameters of the +`Get-ChildItem` cmdlet to get all of the certificates on the computer that have +code-signing authority. + +```powershell +Get-ChildItem -Path cert: -CodeSigningCert -Recurse +``` + +### Find expired certificates + +This command uses the **ExpiringInDays** parameter of the `Get-ChildItem` +cmdlet to get certificates that will expire within the next 30 days. + +```powershell +Get-ChildItem -Path cert:\LocalMachine\WebHosting -ExpiringInDays 30 +``` + +### Find Server SSL Certificates + +This command uses the **SSLServerAuthentication** parameter of the +`Get-ChildItem` cmdlet to get all Server SSL Certificates in the My and +WebHosting stores. + +```powershell +Get-ChildItem -Path cert:\LocalMachine\My, cert:\LocalMachine\WebHosting ` + -SSLServerAuthentication +``` + +### Find expired certificates on remote computers + +This command uses the `Invoke-Command` cmdlet to run a `Get-ChildItem` command +on the Srv01 and Srv02 computers. A value of zero (0) in the **ExpiringInDays** +parameter gets certificates on the Srv01 and Srv02 computers that have expired. + +```powershell +Invoke-Command -ComputerName Srv01, Srv02 {Get-ChildItem -Path cert:\* ` + -Recurse -ExpiringInDays 0} +``` + +### Combining filters to find a specific set of certificates + +This command gets all certificates in the LocalMachine store location that have +the following attributes: + +- "fabrikam" in their DNS name +- "Client Authentication" in their EKU +- a value of `$true` for the **SendAsTrustedIssuer** property +- do not expire within the next 30 days. + +The **NotAfter** property stores the certificate expiration date. + +```powershell +Get-ChildItem -Path cert:\* -Recurse -DNSName "*fabrikam*" ` + -EKU "*Client Authentication*" | Where-Object { + $_.SendAsTrustedIssuer -and ` + $_.NotAfter -gt (get-date).AddDays.(30) + } +``` + +## Opening the Certificates MMC Snap-in + +The `Invoke-Item` cmdlet will use the default application to open a path +you specify. For certificates, the default application is the Certificates MMC +snap-in. + +This command opens the Certificates MMC snap-in to manage the specified +certificate. + +```powershell +Invoke-Item cert:\CurrentUser\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B +``` + +## Copying Certificates + +Copying certificates is not supported by the **Certificate** provider. When +you attempt to copy a certificate, you see this error. + +``` +$path = "Cert:\LocalMachine\Root\E2C0F6662D3C569705B4B31FE2CBF3434094B254" +PS Cert:\LocalMachine\> Copy-Item -Path $path -Destination .\CA\ +Copy-Item : Provider operation stopped because the provider does not support +this operation. +At line:1 char:1 ++ Copy-Item -Path $path -Destination .\CA\ ++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + CategoryInfo : NotImplemented: (:) [Copy-Item], + PSNotSupportedException + + FullyQualifiedErrorId : NotSupported, + Microsoft.PowerShell.Commands.CopyItemCommand +``` + +## Moving Certificates + +### Move all SSL Server authentication certs to the WebHosting store + +This command uses the `Move-Item` cmdlet to move a certificate from the My +store to the WebHosting store. + +`Move-Item` will not move certificate stores and it will not move certificates +to a different store location, such as moving a certificate from LocalMachine +to CurrentUser. The `Move-Item` cmdlet moves certificates, but it does not move +private keys. + +This command uses the **SSLServerAuthentication** parameter of the +`Get-ChildItem` cmdlet to get SSL server authentication certificates in the MY +certificate store. + +The returned certificates are piped to the `Move-Item` cmdlet, which moves +the certificates to the WebHosting store. + +```powershell +Get-ChildItem cert:\LocalMachine\My -SSLServerAuthentication | Move-Item ` + -Destination cert:\LocalMachine\WebHosting +``` + +## Deleting Certificates and Private Keys + +The `Remove-Item` cmdlet will remove certificates that you specify. The +`-DeleteKey` dynamic parameter deletes the private key. + +### Delete a Certificate from the CA store + +This command deletes a certificate from the CA certificate store, but leaves +the associated private key intact. + +In the `Cert:` drive, the `Remove-Item` cmdlet supports only the **DeleteKey**, +**Path**, **WhatIf**, and **Confirm** parameters. All other parameters are +ignored. + +```powershell +Remove-Item cert:\LocalMachine\CA\5DDC44652E62BF9AA1116DC41DE44AB47C87BDD0 +``` + +### Delete a Certificate using a wildcards in the DNS name + +This command deletes all certificates that have a DNS name that contains +"Fabrikam". It uses the **DNSName** parameter of the `Get-ChildItem` cmdlet to +get the certificates and the `Remove-Item` cmdlet to delete them. + +```powershell +Get-ChildItem -Path cert:\LocalMachine -DnsName *Fabrikam* | Remove-Item +``` + +### Delete private keys from a remote computer + +This series of commands enables delegation and then deletes the certificate and +associated private key on a remote computer. To delete a private key on a +remote computer, you must use delegated credentials. + +Use the `Enable-WSManCredSSP` cmdlet to enable Credential Security Service +Provider (CredSSP) authentication on a client on the S1 remote computer. +CredSSP permits delegated authentication. + +```powershell +Enable-WSManCredSSP -Role Client -DelegateComputer S1 +``` + +Use the `Connect-WSMan` cmdlet to connect the S1 computer to the WinRM service on +the local computer. When this command completes, the S1 computer appears in the +local `WSMan:` drive in PowerShell. + +```powershell +Connect-WSMan -ComputerName S1 -Credential Domain01\Admin01 +``` + +Now, you can use the Set-Item cmdlet in the WSMan: drive to enable the CredSSP +attribute for the WinRM service. + +```powershell +Set-Item -Path WSMan:\S1\Service\Auth\CredSSP -Value $true +``` + +Start a remote session on the s1 computer using the `New-PSSession` cmdlet, and +specify CredSSP authentication. Saves the session in the `$s` variable. + +```powershell +$s = New-PSSession S1 -Authentication CredSSP -Credential Domain01\Admin01 +``` + +Finally, use the `Invoke-Command` cmdlet to run a `Remove-Item` command in the +session in the `$s` variable. The `Remove-Item` command uses the **DeleteKey** +parameter to remove the private key along with the specified certificate. + +```powershell +Invoke-Command -Session $s { Remove-Item ` + -Path cert:\LocalMachine\My\D2D38EBA60CAA1C12055A2E1C83B15AD450110C2 ` + -DeleteKey + } +``` + +### Delete expired Certificates + +This command uses the **ExpiringInDays** parameter of the `Get-ChildItem` +cmdlet with a value of 0 to get certificates in the WebHosting store that have +expired. + +The variable containing the returned certificates is piped to the +`Remove-Item` cmdlet, which deletes them. The command uses the **DeleteKey** +parameter to delete the private key along with the certificate. + +```powershell +$expired = Get-ChildItem cert:\LocalMachine\WebHosting -ExpiringInDays 0 +$expired | Remove-Item -DeleteKey +``` + +## Creating Certificates + +The `New-Item` cmdlet does not create new certificates in the **Certificate** +provider. Use the [New-SelfSignedCertificate](/powershell/module/pkiclient/new-selfsignedcertificate) cmdlet to create a certificate +for testing purposes. + +## Creating Certificate Stores + +In the Cert: drive, the `New-Item` cmdlet creates certificate stores in the +LocalMachine store location. It supports the **Name**, **Path**, **WhatIf**, +and **Confirm** parameters. All other parameters are ignored. The command +returns a **System.Security.Cryptography.X509Certificates.X509Store** +that represents the new certificate store. + +This command creates a new certificate store named "CustomStore" in the +LocalMachine store location. + +```powershell +New-Item -Path cert:\LocalMachine\CustomStore +``` + +### Create a new certificate store on a remote computer + +This command creates a new certificate store named "HostingStore" in the +LocalMachine store location on the Server01 computer. + +The command uses the `Invoke-Command` cmdlet to run a `New-Item` command on the +Server01 computer. The command returns a +**System.Security.Cryptography.X509Certificates.X509Store** that represents +the new certificate store. + +```powershell +Invoke-Command { New-Item -Path cert:\LocalMachine\CustomStore } ` + -ComputerName Server01 +``` + +## Creating Client Certificates for WS-Man + +This command creates **ClientCertificate** entry that can be used by the +**WS-Management** client. The new **ClientCertificate** will show up under the +**ClientCertificate** directory as "ClientCertificate_1234567890". All of the +parameters are mandatory. The **Issuer** needs to be thumbprint of the issuers +certificate. + +```powershell +$cred = Get-Credential +New-Item -Path WSMan:\localhost\ClientCertificate ` + -Issuer 1b3fd224d66c6413fe20d21e38b304226d192dfe ` + -URI wmicimv2/* -Credential $cred +``` + +## Deleting Certificate Stores + +### Delete a certificate store from a remote computer + +This command uses the `Invoke-Command` cmdlet to run a `Remove-Item` command on +the S1 and S2 computers. The `Remove-Item` command includes the **Recurse** +parameter, which deletes the certificates in the store before it deletes the +store. + +```powershell +Invoke-Command { Remove-Item -Path cert:\LocalMachine\TestStore -Recurse } ` + -ComputerName S1, S2 +``` + +## 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. + +## 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. These parameters are valid in all subdirectories of the +Certificate provider, but are effective only on certificates. + +> [!NOTE] +> Parameters that perform filtering against the `EnhancedKeyUsageList` property +> also return items with an empty `EnhancedKeyUsageList` property value. +> Certificates that have an empty **EnhancedKeyUsageList** can be used for +> all purposes. + +### CodeSigningCert + +#### Cmdlets supported + +- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +This parameter gets certificates that have "Code Signing" in their +**EnhancedKeyUsageList** property value. + +### DnsName + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +This parameter gets certificates that have the specified domain name or name +pattern in the **DNSNameList** property of the certificate. The value of this +parameter can either be "Unicode" or "ASCII". Punycode values are converted to +Unicode. Wildcard characters (*) are permitted. + +This parameter was introduced in Windows PowerShell 3.0. + +### EKU + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +This parameter gets certificates that have the specified text or text pattern +in the `EnhancedKeyUsageList` property of the certificate. Wildcard characters +(*) are permitted. The `EnhancedKeyUsageList` property contains the friendly +name and the OID fields of the EKU. + +This parameter was introduced in Windows PowerShell 3.0. + +### ExpiringInDays + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +This parameter gets certificates that are expiring in or before the specified +number of days. A value of 0 (zero) gets certificates that have expired. + +This parameter was introduced in Windows PowerShell 3.0. + +### SSLServerAuthentication + +#### Cmdlets supported + +- [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) + +Gets only server certificates for SSL web hosting. This parameter gets +certificates that have "Server Authentication" in their `EnhancedKeyUsageList` +property value. + +This parameter was introduced in Windows PowerShell 3.0. + +### DeleteKey + +#### Cmdlets supported + +- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) + +This parameter deletes the associated private key when it deletes the certificate. + +> [!IMPORTANT] +> To delete a private key that is associated with a user certificate in the +> `Cert:\CurrentUser` store on a remote computer, you must use delegated +> credentials. The `Invoke-Command` cmdlet supports credential delegation +> using the **CredSSP** parameter. You should consider any security risks +> before using `Remove-Item` with `Invoke-Command` and credential delegation. + +This parameter was introduced in Windows PowerShell 3.0. + +## Script properties + +New script properties have been added to the **x509Certificate2** object that +represents the certificates to make it easy to search and manage the +certificates. + +- `DnsNameList`: To populate the `DnsNameList` property, the Certificate + provider copies the content from the DNSName entry in the + SubjectAlternativeName (SAN) extension. If the SAN extension is empty, the + property is populated with content from the Subject field of the certificate. + +- `EnhancedKeyUsageList`: To populate the `EnhancedKeyUsageList` property, the + Certificate provider copies the OID properties of the EnhancedKeyUsage (EKU) + field in the certificate and creates a friendly name for it. + +- `SendAsTrustedIssuer`: {{Fill in description https://docs.microsoft.com/en-us/dotnet/api/microsoft.powershell.commands.sendastrustedissuerproperty?redirectedfrom=MSDN&view=powershellsdk-1.1.0}} + +These new features let you search for certificates based on their DNS names and +expiration dates, and distinguish client and server authentication certificates +by the value of their Enhanced Key Usage (EKU) properties. + +## 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](../../Microsoft.PowerShell.Core/Get-Help.md) command in a file system drive or use the `-Path` +parameter of [Get-Help](../../Microsoft.PowerShell.Core/Get-Help.md) to specify a file system drive. + +```powershell +Get-Help Get-ChildItem +``` + +```powershell +Get-Help Get-ChildItem -Path c: +``` + +{{Make provider specific>}} + +## See also + +[about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) + +[about_Signing](../../Microsoft.PowerShell.Core/About/about_Signing.md) + +[Get-AuthenticodeSignature](../Get-AuthenticodeSignature.md) + +[Set-AuthenticodeSignature](../Set-AuthenticodeSignature.md) + +[Get-PfxCertificate](../Get-PfxCertificate.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Security/Providers/get-childitem-for-certificate.md b/reference/6/Microsoft.PowerShell.Security/Providers/get-childitem-for-certificate.md deleted file mode 100644 index 46ec5501bab3..000000000000 --- a/reference/6/Microsoft.PowerShell.Security/Providers/get-childitem-for-certificate.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Get-ChildItem for Certificate -online version: http://go.microsoft.com/fwlink/?LinkId=834969 ---- - -# Get-ChildItem for Certificate -Gets certificate store locations, certificate stores, and certificates in the Windows PowerShell Cert: drive. - -## Syntax - -``` -Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringInDays ] [-SSLServerAuthentication] [] - -``` - -## Description - In the Cert: drive, the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet gets certificate store locations, certificate stores, and certificates. The PowerShell [Certificate Provider](Certificate-Provider.md) adds the Cert: drive to PowerShell. - - Beginning in Windows PowerShell 3.0, the Certificate provider enhances its support for managing Secure Socket Layer (SSL) certificates for web hosting. New filtering parameters, DnsName, EKU, ,ExpiringInDays, and SSLServerAuthentication have been added to [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) to enable you to search for certificates based on their DNS names and expiration dates, and distinguish client and server authentication certificates by the value of their Enhanced Key Usage (EKU) properties. The new dynamic parameters work in Windows PowerShell 3.0 and newer releases of Windows PowerShell, running on Windows 8, Windows Server 2012 and newer releases of the Windows operating system. - - Also, new script properties, DnsNameList and EnhancedKeyUsageList, and SendAsTrustedIssuer, have been added to the x509Certificate2 object that represents the certificates to make it easy to search and manage the certificates. - - To populate the DnsNameList property, the Certificate provider copies the content from the DNSName entry in the SubjectAlternativeName (SAN) extension. If the SAN extension is empty, the property is populated with content from the Subject field of the certificate. To populate the EnhancedKeyUsageList property, the Certificate provider copies the content from the Friendly Name and OID properties of the EnhancedKeyUsage (EKU) field in the certificate. - - NOTE: The Name parameter of [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) is not supported in the Cert: drive. To indicate items in the Cert: drive, use the Path parameter. - -## Parameters - -### -CodeSigningCert - Gets only those certificates with code-signing authority. This parameter gets certificates that have "Code Signing" in their EnhancedKeyUsageList property value. - - Because certificates that have an empty EnhancedKeyUsageList can be used for all purposes, searches for code signing certificates also return certificates that have an empty EnhancedKeyUsageList property value. - - This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - - This parameter was introduced in Windows PowerShell 1.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|False| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -DocumentEncryptionCert - Gets those certificates in the certificate provider that are used for document encryption. Document encryption certificates have a value of "{text}%szOID_DOCUMENT_ENCRYPTION%" for the EnhancedKeyUsageList property. - - This parameter was introduced in Windows PowerShell 5.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|False| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -DnsName - Gets certificates that have the specified domain name or name pattern in the DNSNameList property of the certificate. The value of the DnsName parameter can either be Unicode or ASCII. Punycode values are converted to Unicode. Wildcard characters (*) are permitted. - - This parameter was introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|None| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|true| - -### -EKU - Gets certificates that have the specified text or text pattern in the EnhancedKeyUsageList property of the certificate. Wildcard characters (*) are permitted. The EnhancedKeyUsageList property contains the friendly name and the OID fields of the EKU. - - Because certificates that have an empty EnhancedKeyUsageList can be used for all purposes, all EKU searches return certificates that have an empty EnhancedKeyUsageList property value. - - This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - - This parameter was introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|None| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|true| - -### -ExpiringInDays - Gets certificates that are expiring in or before the specified number of days. Enter an integer. A value of 0 (zero) gets certificates that have expired. This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - - The ExpiringInDays parameter uses the value of the NotAfter property of the certificate, which stores the expiration date of the certificate. The effective date is stored in the NotBefore property of the certificate. - - This parameter was introduced in Windows PowerShell 3.0. It runs on Windows 8, Windows Server 2012, and newer releases of the Windows operating system. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|None| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -SSLServerAuthentication - Gets only server certificates for SSL web hosting. This parameter gets certificates that have "Server Authentication" in their EnhancedKeyUsageList property value. - - Because certificates that have an empty EnhancedKeyUsageList can be used for all purposes, SSLServerAuthentication searches also return certificates that have an empty EnhancedKeyUsageList property value. - - This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - - This parameter was introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|False| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.String

In the Cert: drive, you can pipe a path to Get-ChildItem.| -|Outputs|Microsoft.PowerShell.Commands.X509StoreLocation, System.Security.Cryptography.X509Certificates.X509Store, System.Security.Cryptography.X509Certificates.X509Certificate2, System.String

In the Cert: drive, Get-ChildItem returns objects that represent certificate store locations, certificate stores, and certificates. When you use the Name parameter, it returns the object name as a string.| - -## Notes - -- Beginning in Windows PowerShell 3.0, the Microsoft.PowerShell.Security module that contains the Cert: drive is not imported automatically into every session. To use the Cert: drive, use the [Import-Module](../../Microsoft.PowerShell.Core/Import-Module.md) cmdlet to import the module, or run a command that uses the Cert: drive, such as a "[Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) Cert:" command. - - -- The CodeSigningCert, DnsName, EKU, and ExpiringInParameter parameters are valid in all subdirectories of the Certificate provider, but they are effective only on certificates. - -## Example 1 - -``` -C:\PS>PS cert:\> Get-ChildItem - -Location : CurrentUser -StoreNames : {TrustedPublisher, ClientAuthIssuer, Root, UserDS...} - -Location : LocalMachine -StoreNames : {TrustedPublisher, ClientAuthIssuer, Remote Desktop, Root...} - -Description ------------ -At the root of the Cert: drive, the Get-ChildItem cmdlet gets certificate store locations. - -``` - -## Example 2 - -``` -C:\PS>PS cert:\LocalMachine\> Get-ChildItem - -Name : TrustedPublisher - -Name : ClientAuthIssuer - -Name : Remote Desktop - -Name : Root - -Name : KRA - -Name : TrustedDevices - -Name : WebHosting - -Name : CA - -Name : REQUEST - -Name : AuthRoot - -Name : TrustedPeople - -Name : My - -Name : SmartCardRoot - -Name : Trust - -Name : Disallowed - -Description ------------ -In a certificate store location in Cert: drive, the Get-ChildItem cmdlet gets certificate stores. - -``` - -## Example 3 - -``` -C:\PS>PS cert:\LocalMachine\My\> Get-ChildItem - -Thumbprint Subject ----------- ------- -D259F7B1DA04D41451866A2D464EC4A71BCBEDCD CN=fabrikam-v6_CA, OU=Microsoft PKI Team -5B047DCA542A9E46C0EC7BF1AD7889612CADAA2E CN=fabrikam-V6.dfabrikam-v5.fabrikam.com -3A37D8CEAA95E4FD099FC87F7E2779813D6BF4CC CN=fabrikam-V6.dfabrikam-v5.fabrikam.com -2E0334D695038DFA40C1D982E5C296EFECA893BB CN=fabrikam-V6.dfabrikam-v5.fabrikam.com -2C85D4CE7A0FA08FF66A4397B2F410071913D03B CN=fabrikam-V6.dfabrikam-v5.fabrikam.com - -Description ------------ -In a certificate store in Cert: drive, the Get-ChildItem cmdlet gets certificates. - -``` - -## Example 4 - -``` -C:\PS>PS cert:\LocalMachine\My\> Get-ChildItem -Path D259F7B1DA04D41451866A2D464EC4A71BCBEDCD | Format-List -Property * - -PSPath : Certificate::LocalMachine\my\5B047DCA542A9E46C0EC7BF1AD7889612CADAA2E -PSParentPath : Certificate::LocalMachine\my -PSChildName : 5B047DCA542A9E46C0EC7BF1AD7889612CADAA2E -PSDrive : cert -PSProvider : Certificate -PSIsContainer : False -EnhancedKeyUsageList : {Client Authentication (1.3.6.1.5.5.7.3.2), Server Authentication (1.3.6.1.5.5.7.3.1)} -DnsNameList : {fabrikam-V6.dfabrikam-v5.fabrikam.com} -Archived : False -Extensions : {System.Security.Cryptography.Oid, System.Security.Cryptography.Oid, - System.Security.Cryptography.Oid, System.Security.Cryptography.Oid...} -FriendlyName : -IssuerName : System.Security.Cryptography.X509Certificates.X500DistinguishedName -NotAfter : 4/21/2012 10:08:18 AM -NotBefore : 4/22/2011 10:08:18 AM -HasPrivateKey : True -PrivateKey : -PublicKey : System.Security.Cryptography.X509Certificates.PublicKey -RawData : {48, 130, 6, 124...} -SerialNumber : 220000000485E38FCF54250BCD000000000004 -SubjectName : System.Security.Cryptography.X509Certificates.X500DistinguishedName -SignatureAlgorithm : System.Security.Cryptography.Oid -Thumbprint : 5B047DCA542A9E46C0EC7BF1AD7889612CADAA2E -Version : 3 -Handle : 545160087216 -Issuer : CN=fabrikam-v6_CA, OU=Microsoft PKI Team -Subject : CN=fabrikam-V6.dfabrikam-v5.fabrikam.com - -Description ------------ -This command displays all of the properties and property values of a certificate in a list. It uses the Get-ChildItem cmdlet to get the certificate and the Format-List cmdlet to display the properties. - -If the value of a property is an object name, use dot notation to display the object value. For example, "(Get-ChildItem -Path D259F7B1DA04D41451866A2D464EC4A71BCBEDCD).IssuerName". - -``` - -## Example 5 - -``` -C:\PS>Get-ChildItem -Path cert: -CodeSigningCert -Recurse - -Description ------------ -This command uses the CodeSigningCert and Recurse parameters of the Get-ChildItem cmdlet to get all of the certificates on the computer that have code-signing authority. Because the full path is specified, this command can be run in any PowerShell drive. - -``` - -## Example 6 - -``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\WebHosting -DNSName "*fabrikam*" - -Description ------------ -This command uses the DNSName parameter of the Get-ChildItem cmdlet to get all of the certificates in the WebHosting store whose domain names contain "Fabrikam". - -``` - -## Example 7 - -``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\WebHosting -ExpiringInDays 30 - -Description ------------ -This command uses the ExpiringInDays parameter of the Get-ChildItem cmdlet to get certificates that will expire within the next 30 days. - -``` - -## Example 8 - -``` -C:\PS>Invoke-Command -ComputerName Srv01, Srv02 -ScriptBlock {Get-ChildItem -Path cert:\* -Recurse -ExpiringInDays 0} - -Description ------------ -This command uses the Invoke-Command cmdlet to run a Get-ChildItem command on the Srv01 and Srv02 computers. A value of zero (0) in the ExpiringInDays parameter gets all certificates on the Srv01 and Srv02 computers that have expired. - -``` - -## Example 9 - -``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\My, cert:\LocalMachine\WebHosting -EKU "Server Authentication" - -Description ------------ -This command uses the EKU parameter of the Get-ChildItem cmdlet to get all Server SSL Certificates in the My and WebHosting stores. - -``` - -## Example 10 - -``` -C:\PS>Get-ChildItem -Path cert:\* -Recurse -DNSName "*fabrikam*" -EKU "*Server*" | Where-Object {$_.SendAsTrustedIssuer -and $_.NotAfter -gt (get-date).AddDays.(30)} - -Description ------------ -This command gets all certificates in the LocalMachine store location that have "fabrikam" in their DNS name, "Server" in their EKU, a value of $true for the SendAsTrustedIssuer property, and do not expire within the next 30 days. The NotAfter property stores the certificate expiration date. - -``` - -## See Also - [Certificate Provider](Certificate-Provider.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Get-PfxCertificate](https://msdn.microsoft.com/en-us/powershell/reference/5.1/Microsoft.PowerShell.Security/Get-PfxCertificate) - [Get-PSDrive](../../Microsoft.PowerShell.Management/Get-PSDrive.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Security/Providers/move-item-for-certificate.md b/reference/6/Microsoft.PowerShell.Security/Providers/move-item-for-certificate.md deleted file mode 100644 index a6eca81dcd3e..000000000000 --- a/reference/6/Microsoft.PowerShell.Security/Providers/move-item-for-certificate.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Move-Item for Certificate -online version: http://go.microsoft.com/fwlink/?LinkId=834970 ---- - -# Move-Item for Certificate -Moves certificates from one certificate store to another certificate store. - -## Syntax - -``` -Move-Item [-Path] [[-Destination] ] [-Confirm] [-WhatIf] [] - -``` - -## Description - In the Cert: drive, [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) moves certificates from one certificate store to another certificate store. The PowerShell [Certificate Provider](Certificate-Provider.md) adds the Cert: drive to PowerShell. - - Beginning in Windows PowerShell 3.0, the Certificate provider enhances its support for managing Secure Socket Layer (SSL) certificates for web hosting by enabling you to use the [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) cmdlet to move certificates between certificate stores. You cannot use this feature to move a certificate to a different certificate store location, such as a move from LocalMachine to CurrentUser, or to move certificate stores. Also, [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) does not move private keys. - - NOTE: In the Cert: drive, only the Path, Destination, WhatIf, and Confirm parameters of the [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) cmdlet are effective. All other parameter and parameter values are ignored. - -## Parameters - -### -Destination - Specifies the path to the location where the items are being moved. The default is the current certificate store. Wildcards - - are permitted, but the result must specify a single location. - - To rename the item that is being moved, specify a new name in the value of the Destination parameter. - -||| -|-|-| -|Required?|false| -|Position?|2| -|Default Value|Current certificate store| -|Accept Pipeline Input?|true (ByValue, ByPropertyName)| -|Accept Wildcard Characters?|false| - -### -Path - Specifies the path to the original location of the certificate. Wildcards are permitted. - -||| -|-|-| -|Required?|true| -|Position?|1| -|Default Value|None| -|Accept Pipeline Input?|true (ByValue, ByPropertyName)| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.String

You can pipe a certificate path to the Move-Item cmdlet.| -|Outputs|None

This cmdlet does not generate any output.| - -## Notes - -- Beginning in Windows PowerShell 3.0, the Microsoft.PowerShell.Security module that contains the Cert: drive is not imported automatically into every session. To use the Cert: drive, use the [Import-Module](../../Microsoft.PowerShell.Core/Import-Module.md) cmdlet to import the module, or run a command that uses the Cert: drive, such as a "[Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) Cert:" command. - -## Example 1 - -``` -C:\PS>Move-Item -Path cert:\LocalMachine\My\5DDC44652E62BF9AA1116DC41DE44AB47C87BDD0 -Destination cert:\LocalMachine\WebHosting - -Description ------------ -This command uses the Move-Item cmdlet to move a certificate from the My store to the WebHosting store. - -Because the command uses absolute paths, you can run it from any PowerShell drive. You can also run it from a Cert: drive path and use relative paths. - -``` - -## Example 2 - -``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\My -EKU "Server Authentication" | Move-Item -Destination cert:\LocalMachine\WebHosting - -Description ------------ -This command uses the EKU parameter of the Get-ChildItem cmdlet to get SSL server authentication certificates in the MY certificate store. - -It uses a pipeline operator to send the certificates to the Move-Item cmdlet, which moves the certificates to the WebHosting store. - -``` - -## See Also - [Certificate Provider](Certificate-Provider.md) - [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Get-PfxCertificate](https://msdn.microsoft.com/en-us/powershell/reference/5.1/Microsoft.PowerShell.Security/Get-PfxCertificate) - [Get-PSDrive](../../Microsoft.PowerShell.Management/Get-PSDrive.md) - [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Security/Providers/new-item-for-certificate.md b/reference/6/Microsoft.PowerShell.Security/Providers/new-item-for-certificate.md deleted file mode 100644 index 48f235fabf39..000000000000 --- a/reference/6/Microsoft.PowerShell.Security/Providers/new-item-for-certificate.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: New-Item for Certificate -online version: http://go.microsoft.com/fwlink/?LinkId=834971 ---- - -# New-Item for Certificate -Creates new certificate stores in the LocalMachine store location. - -## Syntax - -``` -New-Item [-Path] [-Name ] [-Confirm] [-WhatIf] [] - -New-Item [-Path] [-Confirm] [-WhatIf] [] - -``` - -## Description - In the Cert: drive, the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet creates new certificate stores in the LocalMachine certificate store location. The PowerShell [Certificate Provider](Certificate-Provider.md) adds the Cert: drive to PowerShell. - - Beginning in Windows PowerShell 3.0, the Certificate provider enables you to use the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create new certificate stores. You can also use the [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) cmdlet to delete the certificate stores that you create. You cannot use the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create certificates or certificate store locations, or to create certificate stores in the CurrentUser certficate store location. - - Note: In the Cert: drive, only the Name, Path, WhatIf, and Confirm parameters of [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) are effective. All other parameter and parameter values are ignored. - -## Parameters - -### -Name - Specifies the name the new certificate store. You can use the Name parameter or include the name in the value of the Path parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|true (ByPropertyName)| -|Accept Wildcard Characters?|false| - -### -Path - Specifies the full or relative path to the new certificate store. You can include the name of the certificate store in the path or use the Name parameter to specify the name. - -||| -|-|-| -|Required?|true| -|Position?|1| -|Default Value|| -|Accept Pipeline Input?|true (ByPropertyName)| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|| -|Outputs|System.Security.Cryptography.X509Certificates.X509Store

New-Item returns an X509Store object that represents the new certificate store.| - -## Notes - -- Beginning in Windows PowerShell 3.0, the Microsoft.PowerShell.Security module that contains the Cert: drive is not imported automatically into every session. To use the Cert: drive, use the [Import-Module](../../Microsoft.PowerShell.Core/Import-Module.md) cmdlet to import the module, or run a command that uses the Cert: drive, such as a "[Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) Cert:" command. - - -- In the Cert: drive, the ItemType parameter is ignored. You do not need to specify an item type to create a certificate store. - -## Example 1 - -``` -C:\PS>New-Item -Path Cert:\LocalMachine\TestStore - -Name : TestStore - -Description ------------ -This command uses the New-Item cmdlet to create the "TestStore" certificate store in the LocalMachine store location. - -The command returns a System.Security.Cryptography.X509Certificates.X509Store that represents the new certificate store. - -``` - -## Example 2 - -``` -C:\PS>New-Item -Path Cert:\LocalMachine -Name TestStore - -Name : TestStore - -Description ------------ -This command uses the New-Item cmdlet to create the "TestStore" certificate store in the LocalMachine store location. It is identical to the previous command, but it uses the Name parameter to specify the store name, instead of the Path parameter. The effect is identical. - -``` - -## Example 3 - -``` -C:\PS>Invoke-Command -ComputerName Server01 { New-Item -Path Cert:\LocalMachine\TestStore } - -Description ------------ -This command creates the TestStore certificate store on the Server01 remote computer. It uses the Invoke-Command cmdlet to run the New-Item command remotely. - -``` - -## See Also - [Certificate Provider](Certificate-Provider.md) - [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Get-PSDrive](../../Microsoft.PowerShell.Management/Get-PSDrive.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Security/Providers/remove-item-for-certificate.md b/reference/6/Microsoft.PowerShell.Security/Providers/remove-item-for-certificate.md deleted file mode 100644 index 5c6c61010378..000000000000 --- a/reference/6/Microsoft.PowerShell.Security/Providers/remove-item-for-certificate.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: Remove-Item for Certificate -online version: http://go.microsoft.com/fwlink/?LinkId=834972 ---- - -# Remove-Item for Certificate -Deletes certificate stores, certificates, and private keys. - -## Syntax - -``` -Remove-Item [-Path] [-DeleteKey] [-Confirm] [-WhatIf] [] - -``` - -## Description - In the Cert: drive, the Remove-Item cmdlet deletes certificates and their associated private keys. It also deletes certificate stores in the LocalMachine certificate store location that you create by using the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet. The PowerShell [Certificate Provider](Certificate-Provider.md) adds the Cert: drive to PowerShell. - - Beginning in Windows PowerShell 3.0, the Certificate provider enhances its support for managing Secure Socket Layer (SSL) certificates for web hosting by enabling you to use the Remove-Item cmdlet to delete certificates and private keys, and to delete user-created certificate stores in the LocalMachine certificate store location. However, you cannot use this feature to delete certificate store locations, such as CurrentUser or LocalMachine, or certificate stores that Windows creates. - - Note: In the Cert: drive, only the DeleteKey, Path, WhatIf, and Confirm parameters of Remove-Item are effective. All other parameter and parameter values are ignored. - -## Parameters - -### -DeleteKey - Deletes the associated private key when it deletes the certificate. - - To delete a private key that is associated with a user certificate in the Cert:\CurrentUser store location on a remote computer, you must use delegated credentials. When using the [Invoke-Command](../../Microsoft.PowerShell.Core/Invoke-Command.md) cmdlet to run a Remove-Item command remotely, after considering the security risks, use the CredSSP parameter to enable delegation. This parameter is valid in all subdirectories of the Certificate provider, but it is effective only on certificates. - - This parameter was introduced in Windows PowerShell 3.0. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|False| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Path - Specifies the path to the certificates and certificate stores that are being deleted. Wildcards are permitted. The parameter name ("-Path") is optional. - -||| -|-|-| -|Required?|true| -|Position?|1| -|Default Value|| -|Accept Pipeline Input?|true (ByValue, ByPropertyName)| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.String

You can pipe a path to the Remove-Item cmdlet in the Cert: drive.| -|Outputs|None

This cmdlet does not generate any output.| - -## Notes - -- Beginning in Windows PowerShell 3.0, the Microsoft.PowerShell.Security module that contains the Cert: drive is not imported automatically into every session. To use the Cert: drive, use the [Import-Module](../../Microsoft.PowerShell.Core/Import-Module.md) cmdlet to import the module, or run a command that uses the Cert: drive, such as a "[Set-Location](../../Microsoft.PowerShell.Management/Set-Location.md) Cert:" command. - -## Example 1 - -``` -C:\PS>Remove-Item -Path cert:\LocalMachine\CA\5DDC44652E62BF9AA1116DC41DE44AB47C87BDD0 - -Description ------------ -This command deletes a certificate from the CA certificate store, but leaves the associated private key intact. - -``` - -## Example 2 - -``` -C:\PS># Delete a certificate and private key on a remote computer - -Description ------------ -This series of commands enables delegation and then deletes the certificate and associated private key on a remote computer. To delete a private key on a remote computer, you must use delegated credentials. - -The first command uses the Enable-WSManCredSSP cmdlet to enable Credential Security Service Provider (CredSSP) authentication on a client on the S1 remote computer. CredSSP permits delegated authentication. - -PS C:\> Enable-WSManCredSSP -Role Client -DelegateComputer S1 - -The second command uses the Connect-WSMan cmdlet to connect the S1 computer to the WinRM service on the local computer. When this command completes, the S1 computer appears in the local WSMan: drive in PowerShell. - -PS C:\> Connect-WSMan -ComputerName S1 -Credential Domain01\Admin01 - -The third command uses the Set-Item cmdlet in the WSMan: drive to enable the CredSSP attribute for the WinRM service. - -PS C:\> Set-Item -Path WSMan:\S1\Service\Auth\CredSSP -Value $true - -The fourth command uses the New-PSSession cmdlet to start a remote session on the S1 computer with CredSSP authentication. It saves the session in the $s variable. - -PS C:\> $s = New-PSSession S1 -Authentication CredSSP -Credential Domain01\Admin01 - -The fifth command uses the Invoke-Command cmdlet to run a Remove-Item command in the session in the $s variable. The Remove-Item command uses the DeleteKey parameter to remove the private key along with the specified certificate. - -PS C:\> Invoke-Command -Session $s { Remove-Item cert:\LocalMachine\My\D2D38EBA60CAA1C12055A2E1C83B15AD450110C2 -DeleteKey } - -``` - -## Example 3 - -``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\WebHosting -ExpiringInDays 0 | Remove-Item -DeleteKey - -Description ------------ -This command uses the ExpiringInDays parameter of the Get-ChildItem cmdlet with a value of 0 to get certificates in the WebHosting store that have expired. - -It uses a pipeline operator to pass the certificates to the Remove-Item cmdlet, which deletes them. The command uses the DeleteKey parameter to delete the private key along with the certificate. - -``` - -## Example 4 - -``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine -DnsName *Fabrikam* | Remove-Item - -Description ------------ -This command deletes all certificates that have a DNS name that contains "Fabrikam". It uses the DNSName parameter of the Get-ChildItem cmdlet to get the certificates and the Remove-Item cmdlet to delete them. - -``` - -## See Also - [Certificate Provider](Certificate-Provider.md) - [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Get-PfxCertificate](https://msdn.microsoft.com/en-us/powershell/reference/5.1/Microsoft.PowerShell.Security/Get-PfxCertificate) - [Get-PSDrive](../../Microsoft.PowerShell.Management/Get-PSDrive.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-ClientCertificate.md b/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-ClientCertificate.md deleted file mode 100644 index c582f1b6bc5b..000000000000 --- a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-ClientCertificate.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: New-Item for ClientCertificate -online version: http://go.microsoft.com/fwlink/?LinkId=834973 ---- - -# New-Item for ClientCertificate -Creates a new item. In this location, the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) command creates a new client certificate. - -## Syntax - -``` -New-Item -Issuer -Subject -ResourceURI -Credential [-Confirm] [-WhatIf] [] - -``` - -## Description - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet creates a new item and sets its value. The types of items that can be created depend upon the location of the item. - - In the ClientCertificate directory, you can use the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create and configure a client certificate. A client certificate is used when the WS-Management client is configured to use certificate authentication. - -## Parameters - -### -Issuer - Specifies the name of the certification authority that issued the certificate. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Subject - Specifies the entity that is identified by the certificate. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -ResourceURI - Specifies the Uniform Resource Identifier (URI) that identifies a specific type of resource, such as a disk or a process, on a computer. - - A URI consists of a prefix and a path to a resource. For example: - - http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk - - http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Credential - Specifies the credentials for a local or a domain account. It cannot be NULL. - - The client computer can specify the credentials to use when creating a shell on a computer. The user name must be specified in the domain\user_name form for a domain user. The user name must be specified in the server_name\user_name format for a local user on a server computer. - - If you use this structure, then it should have both the user name and password fields specified. It can be used with Basic, Digest, Negotiate, or Kerberos authentication. The client must explicitly specify the credentials when either Basic or Digest authentication is used. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.Object

You can pipe a value for the new item to the New-Item cmdlet.| -|Outputs|Any| - -## Notes - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see About_Providers. - -## Example 1 - -``` -C:\PS>$cred = Get-Credential -C:\PS>New-Item -Path WSMan:\localhost\ClientCertificate -Issuer 1b3fd224d66c6413fe20d21e38b304226d192dfe -URI wmicimv2/* -Credential $cred; - -This command creates ClientCertificate entry that can be used by the WS-Management client. The new ClientCertificate will show up under the ClientCertificate directory as ClientCertificate_1234567890. All of the parameters are mandatory. The Issuer needs to be thumbprint of the issuers certificate. - -``` - -## See Also - [about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) - [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-InitializationParameters.md b/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-InitializationParameters.md deleted file mode 100644 index a540ff6aa735..000000000000 --- a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-InitializationParameters.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: New-Item for InitializationParameters -online version: http://go.microsoft.com/fwlink/?LinkId=834974 ---- - -# New-Item for InitializationParameters -Creates a new item. - -## Syntax - -``` -New-Item [-ParamName ] [-ParamValue ] [-Confirm] [-WhatIf] [] - -``` - -## Description - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet creates a new item and sets its value. The types of items that can be created depend upon the location of the item. For example, in the file system, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) is used to create files and folders. In the registry, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) creates registry keys and entries. - - In the InitializationParameters directory, you can use the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create and configure Plugin initialization parameters. - -## Parameters - -### -ParamName - Specifies the display name to use for the initialization parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -ParamValue - Specifies the value of an initialization parameter, which is a plug-in-specific value that is used to specify configuration options. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.Object

You can pipe a value for the new item to the New-Item cmdlet.| -|Outputs|Any| - -## Notes - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see About_Providers. - -## Example 1 - -``` -C:\PS>New-Item -Path WSMan:\localhost\Plugin\TestPlugin\InitializationParameters -ParamName testparametername -ParamValue testparametervalue - -This command creates an Initialization parameter named testparametername in the InitializationParameters directory. - -``` - -## See Also - [about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) - [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Listener.md b/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Listener.md deleted file mode 100644 index 987898577e05..000000000000 --- a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Listener.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: New-Item for Listener -online version: http://go.microsoft.com/fwlink/?LinkId=834976 ---- - -# New-Item for Listener -Creates a new item. - -## Syntax - -``` -New-Item -Address -Transport [-Hostname ] [-Enabled] [-URLPrefix ] [-CertificateThumbprint ] [-Confirm] [-WhatIf] [] - -``` - -## Description - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet creates a new item and sets its value. The types of items that can be created depend upon the location of the item. For example, in the file system, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) is used to create files and folders. In the registry, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) creates registry keys and entries. - - New-Item can also set the value of the items that it creates. For example, when creating a new file, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) can add initial content to the file. - -## Parameters - -### -Address - Specifies the address for which this listener was created. The value can be one of the following: - - --The literal string "*". (The wildcard character (\*) makes the command bind all the IP addresses on all the network adapters.) - - --The literal string "IP:" followed by a valid IP address in either IPv4 dotted-decimal format or in IPv6 cloned-hexadecimal format. - - --The literal string "MAC:" followed by the MAC address of an adapter. For example: MAC:32-a3-58-90-be-cc. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Transport - Specifies the transport to use to send and receive WS-Management protocol requests and responses. The value must be either HTTP or HTTPS. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Hostname - Specifies the host name of the computer on which the WS-Management (WinRM) service is running. The value must be a fully qualified domain name, an IPv4 or IPv6 literal string, or a wildcard character. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Enabled - Specifies whether the listener is enabled or disabled. The default is True. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -URLPrefix - A URL prefix on which to accept HTTP or HTTPS requests. This is a string containing only the characters a-z, A-Z, 9-0, underscore (_) and backslash (/). The string must not start with or end with a backslash (/). For example, if the computer name is SampleMachine, the WS-Management client would specify http://SampleMachine/URLPrefix in the destination address. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -CertificateThumbprint - Specifies the thumbprint of the service certificate. - - This value represents the string of two-digit hexadecimal values in the Thumbprint field of the certificate. It specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts, and they do not work with domain accounts. To get a certificate thumbprint, use the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) or [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlets in the Windows PowerShell Cert: drive. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.Object

You can pipe a value for the new item to the New-Item cmdlet.| -|Outputs|Any| - -## Notes - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see About_Providers. - -## Example 1 - -``` -C:\PS>New-Item -Path WSMan:\localhost\Listener -Address * -Transport HTTP -force - -This command creates an HTTP listener on any IP address on the computer. - -``` - -## See Also - [about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) - [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Plugin.md b/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Plugin.md deleted file mode 100644 index 39c3e2ef6dab..000000000000 --- a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Plugin.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: New-Item for Plugin -online version: http://go.microsoft.com/fwlink/?LinkId=834977 ---- - -# New-Item for Plugin -Creates a new item. - -## Syntax - -``` -New-Item -Plugin -Filename -ResourceURI -Capability [-lang ] -SDKVersion [-xmlns ] -XMLRenderingType [-Confirm] [-WhatIf] [] - -``` - -## Description - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet creates a new item and sets its value. The types of items that can be created depend upon the location of the item. For example, in the file system, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) is used to create files and folders. In the registry, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) creates registry keys and entries. - - New-Item can also set the value of the items that it creates. For example, when creating a new file, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) can add initial content to the file. - -## Parameters - -### -Plugin - Specifies the display name to use for the plug-in. If an error is returned by the plug-in, the display name will be put in the error XML that is returned to the client application. The name is not locale specific. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -FileName - Specifies the file name of the operations plug-in. Any environment variables that are put in this entry will be expanded in the users' context when a request is received. Because each user could have a different version of the same environment variable, each user could have a different plug-in. This entry cannot be blank and must point to a valid plug-in. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -ResourceURI - Specifies the Uniform Resource Identifier (URI) that identifies a specific type of resource, such as a disk or a process, on a computer. - - A URI consists of a prefix and a path to a resource. For example: - - http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk - - http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Capability - Specifies an operation that is supported on this Uniform Resource Identifier (URI). You have to create one entry for each type of operation that the URI supports. The following are valid values: - - -- Create: Create operations are supported on the URI. The SupportFragment attribute is used if the Create operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Delete: Delete operations are supported on the URI. The SupportFragment attribute is used if the Delete operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Enumerate: Enumerate operations are supported on the URI. The SupportFragment attribute is not supported for Enumerate operations and should be set to False. The SupportFiltering attribute is valid, and if the plug-in supports filtering, this attribute should be set to True. This operation is not valid for a URI if Shell operations are also supported. - - -- Get: Get operations are supported on the URI. The SupportFragment attribute is used if the Get operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Invoke: Invoke operations are supported on the URI. The SupportFragment attribute is not supported for Invoke operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Put: Put operations are supported on the URI. The SupportFragment attribute is used if the Put operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Subscribe: Subscribe operations are supported on the URI. The SupportFragment attribute is not supported for Subscribe operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Shell: Shell operations are supported on the URI. The SupportFragment attribute is not supported for Shell operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if any other operation is also supported. If a Shell operation is configured for a URI, Get, Put, Create, Delete, Invoke, and Enumerate operations are processed internally within the WS-Management (WinRM) service to manage shells. As a result, the plug-in cannot handle the operations. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -lang - A string that specifies a language, or a language-region with language and region separated by a hyphen. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -SDKVersion - Specifies the version of the WS-Management plug-in SDK. The only valid value is 1. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -xmlns - A string that specifies specifies a Uniform Resource Name (URN) that uniquely identifies the namespace. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -XMLRenderingType - Specifies the format in which XML is passed to plug-ins through the WSMAN_DATA object. The following are valid values: - - Text: Incoming XML data is contained in a WSMAN_DATA_TYPE_TEXT structure, which represents the XML as a PCWSTR memory buffer. - - XMLReader: Incoming XML data is contained in a WSMAN_DATA_TYPE_WS_XML_READER structure, which represents the XML as an XmlReader object, which is defined in the WebServices.h header file. - -||| -|-|-| -|Required?|true| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.Object

You can pipe a value for the new item to the New-Item cmdlet.| -|Outputs|Any| - -## Notes - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see About_Providers. - -## Example 1 - -``` -C:\PS>New-Item -Path WSMan:\localhost\Plugin -Force -Name "Test Plugin" -File C:\Testplugin.xml - - Where Testplugin.xml contains: - -This command creates (registers) a plug-in for the WS-Management service. This example uses an XML file to load all of the necessary setting to create a plug-in. - -This command creates (registers) a plug-in for the WS-Management service. This example uses an XML file to load all of the necessary setting to create a plug-in. - -``` - -## Example 2 - -``` -C:\PS>New-Item -Path WSMan:\localhost\Plugin -Plugin TestPlugin -FileName %systemroot%\system32\WsmWmiPl.dll -Resource http://schemas.dmtf.org/wbem/wscim/2/cim-schema -SDKVersion 1 -Capability "Get","Put","Invoke","Enumerate" -XMLRenderingType text - -This command creates (registers) a plug-in for the WS-Management service. - -``` - -## See Also - [about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) - [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Resources.md b/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Resources.md deleted file mode 100644 index 72100802499b..000000000000 --- a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Resources.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: New-Item for Resources -online version: http://go.microsoft.com/fwlink/?LinkId=834978 ---- - -# New-Item for Resources -Creates a new item. - -## Syntax - -``` -New-Item [-ResourceURI ] [-SupportsOptions] [-ExactMatch] [-Capability ] [-Confirm] [-WhatIf] [] - -``` - -## Description - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet creates a new item and sets its value. The types of items that can be created depend upon the location of the item. For example, in the file system, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) is used to create files and folders. In the registry, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) creates registry keys and entries. - - In the Resources directory, you can use the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create and configure a Plugin resources. - -## Parameters - -### -ResourceURI - Specifies the Uniform Resource Identifier (URI) that identifies a specific type of resource, such as a disk or a process, on a computer. - - A URI consists of a prefix and a path to a resource. For example: - - http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk - - http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -SupportsOptions - Specifies whether the plug-in supports the use of options, which are passed within the wsman:OptionSet header in a request message. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -ExactMatch - Specifies how to use the security settings that are specified in the Sddl parameter. If the ExactMatch parameter is set to True, the security settings in Sddl are used only to authorize access attempts to the URI exactly as specified by the URI. If ExactMatch is set to false, the security settings in Sddl are used to authorize access attempts to the URIs that begin with the string specified in the URI. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Capability - Specifies an operation that is supported on this Uniform Resource Identifier (URI). You have to create one entry for each type of operation that the URI supports. - - The following are valid values: - - -- Create: Create operations are supported on the URI. The SupportFragment attribute is used if the Create operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Delete: Delete operations are supported on the URI. The SupportFragment attribute is used if the Delete operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Enumerate: Enumerate operations are supported on the URI. The SupportFragment attribute is not supported for Enumerate operations and should be set to False. The SupportFiltering attribute is valid, and if the plug-in supports filtering, this attribute should be set to True. This operation is not valid for a URI if Shell operations are also supported. - - -- Get: Get operations are supported on the URI. The SupportFragment attribute is used if the Get operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Invoke: Invoke operations are supported on the URI. The SupportFragment attribute is not supported for Invoke operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Put: Put operations are supported on the URI. The SupportFragment attribute is used if the Put operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Subscribe: Subscribe operations are supported on the URI. The SupportFragment attribute is not supported for Subscribe operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Shell: Shell operations are supported on the URI. The SupportFragment attribute is not supported for Shell operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if any other operation is also supported. If a Shell operation is configured for a URI, Get, Put, Create, Delete, Invoke, and Enumerate operations are processed internally within the WS-Management (WinRM) service to manage shells. As a result, the plug-in cannot handle the operations. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.Object

You can pipe a value for the new item to the New-Item cmdlet.| -|Outputs|Any| - -## Notes - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see About_Providers. - -## Example 1 - -``` -C:\PS>New-Item -Path WSMan:\localhost\Plugin\TestPlugin\Resources -ResourceUri http://schemas.dmtf.org/wbem/wscim/3/cim-schema -Capability "Enumerate" - -This command creates a resource entry in the Resources directory of TestPlugin. - -``` - -## See Also - [about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) - [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Security.md b/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Security.md deleted file mode 100644 index 6ec1aeb49f3b..000000000000 --- a/reference/6/Microsoft.WSMan.Management/Providers/New-Item-for-Security.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: New-Item for Security -online version: http://go.microsoft.com/fwlink/?LinkId=834979 ---- - -# New-Item for Security -Creates a new item. - -## Syntax - -``` -New-Item [-URI ] [-SDDL ] [-ExactMatch] [-Confirm] [-WhatIf] [] - -``` - -## Description - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet creates a new item and sets its value. The types of items that can be created depend upon the location of the item. For example, in the file system, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) is used to create files and folders. In the registry, [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) creates registry keys and entries. - - In the Security directory, you can use the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create and configure Plugin security. - -## Parameters - -### -URI - Identifies the URI for which access is authorized based on the value of the Sddl parameter. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -SDDL - Specifies the Security Descriptor Definition Language (SDDL) for the access control entry. This identifies the security settings that are used to authorize access to a specified resource URI. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -ExactMatch - Specifies how to use the security settings that are specified in the Sddl parameter. If the ExactMatch parameter is set to True, the security settings in Sddl are used only to authorize access attempts to the URI exactly as specified by the URI. - - If ExactMatch is set to false, the security settings in Sddl are used to authorize access attempts to the URIs that begin with the string specified in the URI. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -Confirm - Prompts you for confirmation before executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. - -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| - -### - This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). - -## Inputs and Outputs - The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns. - -||| -|-|-| -|Inputs|System.Object

You can pipe a value for the new item to the New-Item cmdlet.| -|Outputs|Any| - -## Notes - The [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see About_Providers. - -## Example 1 - -``` -C:\PS>New-Item -path WSMan:\localhost\Plugin\TestPlugin\Resources\Resource_5967683\Security -Sddl "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;SA;GWGX;;;WD)" - -This command creates a security entry in the Security directory of Resource_5967683 (a specific resource). - -``` - -## See Also - [about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) - [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md) - [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) - [Move-Item](../../Microsoft.PowerShell.Management/Move-Item.md) - [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.WSMan.Management/Providers/WSMan-Provider.md b/reference/6/Microsoft.WSMan.Management/Providers/WSMan-Provider.md deleted file mode 100644 index 5b97a2fa296d..000000000000 --- a/reference/6/Microsoft.WSMan.Management/Providers/WSMan-Provider.md +++ /dev/null @@ -1,912 +0,0 @@ ---- -ms.date: 06/09/2017 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: WSMan Provider -online version: http://go.microsoft.com/fwlink/?LinkId=834980 ---- - -# WSMan Provider -## PROVIDER NAME - WSMan - -## DRIVES - WSMan - -## SHORT DESCRIPTION - Provides access to Web Services for Management (WS-Management) configuration information. - -## DETAILED DESCRIPTION - The WSMan provider for Windows PowerShell lets you add, change, clear, and delete WS-Management configuration data on local or remote computers. - - The WSMan provider exposes a Windows PowerShell drive with a directory structure that corresponds to a logical grouping of WS-Management configuration settings. These groupings are known as containers. - - New in Windows PowerShell 3.0 - - Beginning in Windows PowerShell 3.0, the WS-Management provider has been updated to support new properties for session configurations, such as OutputBufferingMode. The session configurations appear as items in the Plugin directory of the WSMan: drive and the properties appear as items in each session configuration. - - You can use commands in the WSMan: drive to change the values of the new properties. However, you cannot use the WSMan: drive in Windows PowerShell 2.0 to change properties that are introduced in Windows PowerShell 3.0. Although no error is generated, the commands are not effective To change these settings, use the WSMan drive in Windows PowerShell 3.0. - - Organization of the WSMan: Drive - - -- Client - - You can configure various aspects of the WS-Management client. The configuration information is stored in the registry. - - -- Service - - You can configure various aspects of the WS-Management service. The configuration information is stored in the registry. - - Note: Service configuration is sometimes referred to as Server configuration. - - -- Shell - - You can configure various aspects of the WS-Management shell, such as the setting to allow remote shell access (AllowRemoteShellAccess) and the maximum number of concurrent users allowed (MaxConcurrentUsers). - - -- Listener - - You can create and configure a listener. A listener is a management service that implements the WS-Management protocol to send and to receive messages. - - -- Plugin - - Plug-ins are loaded and used by the WS-Management service to provide various functions. By default, Windows PowerShell provides three plug-ins: the Event Forwarding plug-in, the Microsoft.PowerShell plug-in, and the Windows Management Instrumentation (WMI) Provider plug-in. These three plug-ins support event forwarding, configuration, and WMI access. - - -- ClientCertificate - - You can create and configure a client certificate. A client certificate is used when the WS-Management client is configured to use certificate authentication. - - Directory Hierarchy of the WSMan Provider - - --------------\- - - The directory hierarchy of the WSMan provider for the local computer is as follows: - - WSMan:\localhost - - --- Client - - --- Service - - --- Shell - - --- Listener - - ------ - - --- Plugin - - ------ Event Forwarding Plugin - - --------- InitializationParameters - - --------- Resources - - ------------ Security - - ------ Microsoft.Powershell - - --------- InitializationParameters - - --------- Resources - - ------------ Security - - ------ WMI Provider - - --------- InitializationParameters - - --------- Resources - - ------------ Security - - --- ClientCertificate - - The directory hierarchy of the WSMan provider for a remote computer is the same as a local computer. However, in order to access the configuration settings of a remote computer, you need to make a connection to the remote computer using [Connect-WSMan](../Connect-WSMan.md). Once a connection is made to a remote computer, the name of the remote computer shows up in the provider. - - WSMan:\\ - - --- Client - - --- Service - - --- Shell - - --- Listener - - ------ - - --- Plugin - - ------ Event Forwarding Plugin - - --------- InitializationParameters - - --------- Resources - - ------------ Security - - ------ Microsoft.Powershell - - --------- InitializationParameters - - --------- Resources - - ------------ Security - - ------ WMI Provider - - --------- InitializationParameters - - --------- Resources - - ------------ Security - - --- ClientCertificate - - Custom Provider Help - - -------------------\- - - The Listener, Plugin (IntitializationParameters, Resources, Security) and ClientCertificate provider paths provide specific [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) support. Type "[Get-Help](../../Microsoft.PowerShell.Core/Get-Help.md)[New-Item](../../Microsoft.PowerShell.Management/New-Item.md)" in the relevant path for custom help. - -## EXAMPLES - -### Navigating the WSMan: Drive - -#### Example 1 - This command uses the Set-Location cmdlet to change the current location to the WSMan: drive. - -``` -Set-Location WSMan: - -``` - -#### Example 2 - This command uses the Set-Location command to change the current location to the root location in the Localhost store location. Use a backslash (\\) or forward slash (/) to indicate a level of the WSMan: drive. - -``` -Set-Location -Path Localhost - -``` - - If you are not in the WSMan: drive, begin the path with the drive name. - -#### Example 3 - This command uses the Set-Location command to change the current location to the root location in the remote system store location. Use a backslash (\\) or forward slash (/) to indicate a level of the WSMan: drive. - -``` -Set-Location -Path WSMan:\SERVER01 - -``` - - If you are not in the WSMan: drive, begin the path with the drive name. -The above command assume that a connection to the remote system already exists. If a connection has not been made to the remote system, then a connection could be make immediately prior to navigating to the root location in the remote system store location. For example: - WSMan-Connect SERVER01 - Set-Location -Path WSMan:\SERVER01 - -#### Example 4 - This command uses the Set-Location command to change the current location to the Client location in the Localhost store location. Use a backslash (\\) or forward slash (/) to indicate a level of the WSMan: drive. - -``` -Set-Location -Path Localhost\Client - -``` - - If you are not in the WSMan: drive, begin the path with the drive name. - -### Displaying the Contents of the WSMan: Drive - -#### Example 1 - This command uses the Get-Childitem cmdlet to display the WS-Management stores in the Localhost store location. - -``` -get-childitem -path WSMan:\Localhost - -``` - - If you are in the WSMan: drive, you can omit the drive name. - -#### Example 2 - This command uses the Get-Childitem cmdlet to display the WS-Management stores in the remote computer (SERVER01) store location. - -``` -get-childitem -path WSMan:\SERVER01 - -``` - - If you are in the WSMan: drive, you can omit the drive name. -The above command assume that a connection to the remote system already exists. If a connection has not been made to the remote system, then a connection could be make immediately displaying the properties and containers in the remote system store location. For example: - WSMan-Connect SERVER01 - get-childitem -path WSMan:\SERVER01 - -#### Example 3 - This command uses the Get-Childitem cmdlet to display the current WS-Management connections. - -``` -get-childitem -path WSMan:\ - -``` - - If you are in the WSMan: drive, you can omit the drive name. - -#### Example 4 - This command uses the Get-Item cmdlet to get the properties and containers in the current store. - -``` -Get-Childitem - -``` - - The above command returns a list of properties and containers. For example: -PS WSMan:\localhost> get-childitem - WSManConfig: Microsoft.WSMan.Management\WSMan::localhost -Name Value Type ----- ----- ---\- -MaxEnvelopeSizekb 150 System.String -MaxTimeoutms 60000 System.String -MaxBatchItems 32000 System.String -MaxProviderRequests 4294967295 System.String -Client Container -Service Container -Shell Container -Listener Container -Plugin Container -ClientCertificate Container - -## DYNAMIC PARAMETERS - Dynamic parameters are cmdlet parameters that are added by a Windows PowerShell provider and are available only when the cmdlet is being used in the provider-enabled drive. - -### Address - Specifies the address for which this listener was created. The value can be one of the following: - - -- The literal string "*". (The wildcard character (\*) makes the command bind all the IP addresses on all the network adapters.) - - -- The literal string "IP:" followed by a valid IP address in either IPv4 dotted-decimal format or in IPv6 cloned-hexadecimal format. - - -- The literal string "MAC:" followed by the MAC address of an adapter. For example: MAC:32-a3-58-90-be-cc. - - Note: The Address value is set when creating a Listener. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -### AllowRemoteShellAccess - Enables access to remote shells. If you set this parameter to False, new remote shell connections will be rejected by the server. The default is True. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### AllowUnEncrypted - Allows the client computer to request unencrypted traffic. By default, the client computer requires encrypted network traffic. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Arguments - Specifies the argument string and the command-line arguments that you want to pass to the custom shell. This parameter is optional. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Basic - Allows the client computer to use Basic authentication. Basic authentication is a scheme in which the user name and password are sent in clear text to the server or proxy. This method is the least secure method of authentication. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Capability - Specifies an operation that is supported on this Uniform Resource Identifier (URI). You have to create one entry for each type of operation that the URI supports. The following are valid values: - - -- Create: Create operations are supported on the URI. The SupportFragment attribute is used if the Create operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Delete: Delete operations are supported on the URI. The SupportFragment attribute is used if the Delete operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Enumerate: Enumerate operations are supported on the URI. The SupportFragment attribute is not supported for Enumerate operations and should be set to False. The SupportFiltering attribute is valid, and if the plug-in supports filtering, this attribute should be set to True. This operation is not valid for a URI if Shell operations are also supported. - - -- Get: Get operations are supported on the URI. The SupportFragment attribute is used if the Get operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Invoke: Invoke operations are supported on the URI. The SupportFragment attribute is not supported for Invoke operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Put: Put operations are supported on the URI. The SupportFragment attribute is used if the Put operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Subscribe: Subscribe operations are supported on the URI. The SupportFragment attribute is not supported for Subscribe operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported. - - -- Shell: Shell operations are supported on the URI. The SupportFragment attribute is not supported for Shell operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if any other operation is also supported. If a Shell operation is configured for a URI, Get, Put, Create, Delete, Invoke, and Enumerate operations are processed internally within the WS-Management (WinRM) service to manage shells. As a result, the plug-in cannot handle the operations. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) - -- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### CbtHardeningLevel - Sets the policy for channel-binding token requirements in authentication requests. The following are valid values: - - -- Strict: Any request will be denied unless a channel-binding token is present. This setting guarantees that all connections are secured by the use of channel-binding tokens. - - -- Relaxed: If a channel-binding token is present in a request, the connection will be secured. If a channel-binding token is not present, the connection will still be accepted. However, it will be vulnerable to attacks that are prevented by the use of channel-binding tokens. - - -- None: Any channel-binding tokens that are supplied are ignored. - - The value of this parameter is only effective for HTTPS connections. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### CertificateThumbprint - Specifies the thumbprint of the service certificate. - - This value represents the string of two-digit hexadecimal values in the Thumbprint field of the certificate. It specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts, and they do not work with domain accounts. To get a certificate thumbprint, use the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) or [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlets in the Windows PowerShell Cert: drive. - -#### Cmdlets supported: - -- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Certificate - Allows the client to be used for certificate authentication. The WS-Management client will try to find the certificate in the computer store. If the client cannot find the certificate in the computer store, the client tries to find it in the current user store. If no matching certificate is found, the user receives an error message. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### CredSSP - Allows the client to use Credential Security Service Provider (CredSSP) authentication. - - CredSSP authentication allows the user to delegate credentials. This option is designed for commands that run on one remote computer but collect data from or run additional commands on other remote computers. - - Caution: CredSSP authentication delegates the user's credentials from the local computer to a remote computer. This practice increases the security risk of the remote operation. If the remote computer is compromised, when credentials are passed to it, the credentials can be used to control the network session. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### HTTP - Specifies the port that the client will use when HTTP is used. By default, HTTP uses port 80. You can specify any value from 1 through 65535. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### HTTPS - Specifies the port that the client will use when HTTPS is used. By default, HTTPS uses port 443. You can specify any value from 1 through 65535. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Digest - Allows the client to use Digest authentication. Digest authentication is a challenge-response scheme that uses a server-specified data string for the challenge. Only the client computer can initiate a Digest authentication request. The client computer sends a request to the server to authenticate and receives a token string from the server. Then, the client computer sends the resource request, including the user name and a cryptographic hash of the password combined with the token string. Digest authentication is supported for HTTP and for HTTPS. WinRM Shell client scripts and applications can specify Digest authentication, but the WS-Management service does not accept Digest authentication. - - Note: Digest authentication over HTTP is not considered secure. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Enabled - Specifies whether the listener is enabled or disabled. The default is True. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### ExactMatch - Specifies how to use the security settings that are specified in the Sddl parameter. If the ExactMatch parameter is set to True, the security settings in Sddl are used only to authorize access attempts to the URI exactly as specified by the URI. If ExactMatch is set to false, the security settings in Sddl are used to authorize access attempts to the URIs that begin with the string specified in the URI. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### FileName - Specifies an input file to use to update the management resource specified by the ResourceURI and SelectorSet. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### FileName (Plugin) - Specifies the file name of the operations plug-in. Any environment variables that are put in this entry will be expanded in the users' context when a request is received. Because each user could have a different version of the same environment variable, each user could have a different plug-in. This entry cannot be blank and must point to a valid plug-in. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### HostName - Specifies the host name of the computer on which the WS-Management (WinRM) service is running. - - The value must be a fully qualified domain name, an IPv4 or IPv6 literal string, or a wildcard character. - -#### Cmdlets supported: - -- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### IdleTimeOut - Specifies the maximum time, in milliseconds, that the remote shell will remain open when there is no user activity in the remote shell. The remote shell is automatically deleted after the time that is specified. You can specify any values from 0 through 2147483647. A value of 0 indicates an infinite time-out. The default is 900000 (15 minutes). - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### IPv4Filter - Specifies the IPv4 addresses that listeners can use. The following are valid values: - - -- If you leave the parameter blank, no IPv4 addresses can be used. - - -- If you enter a wildcard character (*), any IPv4 address can be used. - - -- If you enter a list of IP ranges, any IP address in the specified ranges can be used. Separate the ranges by using a comma (,), and specify each range as a pair of IPv4 addresses in dotted-decimal format, separated by a hyphen (-). Make sure that the smaller value occurs first in the pair. The ranges are inclusive. - - Note: An IPv4 literal string consists of four dotted decimal numbers, each in the range 0 though 255. For example: 192.168.0.0. - -#### Cmdlets supported: - -- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### IPv6Filter - Specifies the IPv6 addresses that listeners can use. The following are valid values: - - -- If you leave the parameter blank, no IPv6 addresses can be used. - - -- If you enter a wildcard character (*), any IPv6 address can be used. - - -- If you enter a list of IP ranges, any IP address in the specified ranges can be used. Separate the ranges by using a comma (,"), and specify each range as a pair of IPv6 addresses in cloned-hexadecimal format, separated by a hyphen (-). Make sure that the smaller value occurs first in the pair. The ranges are inclusive. - - Note: An IPv6 literal string is enclosed in brackets and contains hexadecimal numbers that are separated by colons. For example: [::1] or [3ffe:ffff::6ECB:0101]. - -#### Cmdlets supported: - -- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Issuer - Specifies the name of the certification authority that issued the certificate. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Kerberos - Allows the client to use Kerberos authentication. Kerberos authentication is a scheme in which the client and server mutually authenticate by using Kerberos certificates. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### ListeningOn - Specifies the IP address or all the IP addresses on which the service is actually listening. This is derived from the Address element based upon the actual IPs associated with the listener. The value of the IP address must be in IPv4 dotted-decimal notation or in IPv6 colon-delimited hexadecimal notation. Multiple ListeningOn entries exist, each entry starting with ListeningOn_. For example: - - ListeningOn_1201550598 - - ListeningOn_1973755898 - - ListeningOn_1508953035 - - ListeningOn_1560839940 - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -### MaxBatchItems - Specifies the maximum number of elements that can be used in a Pull response. You can specify any value from 1 through 4294967295. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### MaxConcurrentUsers - Specifies the maximum number of users who can concurrently perform remote operations on the same computer through a remote shell. New shell connections will be rejected if they exceed the specified limit. You can specify any value from 1 through 100. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### MaxEnvelopeSizekb - Specifies the maximum SOAP data in kilobytes. You can specify any value from 32 through 4294967295. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### MaxMemoryPerShellMB - Specifies the maximum total amount of memory that can be allocated by an active remote shell and all its child processes. You can specify any value from 0 through 2147483647. A value of 0 means that the ability of the remote operations to allocate memory is limited only by the available virtual memory. The default value is 0. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### MaxProcessesPerShell - Specifies the maximum number of processes that any shell operation is allowed to start. You can specify any number from 0 through 2147483647. A value of 0 allows for an unlimited number of processes. By default, the limit is five processes per shell. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### MaxProviderRequests - Specifies the maximum number of concurrent requests that are allowed by the service. You can specify any value from 1 through 4294967295. The limit is applied per provider. - - Note: This value is deprecated and should not be used. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -### MaxShellsPerUser - Specifies the maximum number of concurrent shells that any user can remotely open on the same system. If this policy setting is enabled, the user will not be able to open new remote shells if the count exceeds the specified limit. If this policy setting is disabled or is not configured, by default, the limit will be set to two remote shells per user. You can specify any number from 0 through 2147483647. A value of 0 allows for an unlimited number of shells. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### MaxTimeoutMs - Specifies the maximum time-out in milliseconds that can be used for any request except for Pull requests. You can specify any number from 500 to 4294967295. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Name - Specifies a display name for the WS-Management session . You can use the name to refer to the session when using other cmdlets, such as [Get-PSSession](../../Microsoft.PowerShell.Core/Get-PSSession.md) and [Enter-PSSession](../../Microsoft.PowerShell.Core/Enter-PSSession.md). The name does not have to be unique to the computer or to the current session. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Name (Plugin) - Specifies the display name to use for the plug-in. If an error is returned by the plug-in, the display name will be put in the error XML that is returned to the client application. The name is not locale specific. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Negotiate - Allows the client to use Negotiate authentication. Negotiate authentication is a scheme in which the client sends a request to the server to authenticate. The server determines whether to use the Kerberos protocol or NTLM. The Kerberos protocol is selected to authenticate a domain account, and NTLM is selected for local computer accounts. The user name must be specified in the domain\user_name form for a domain user. The user name must be specified in the server_name\user_name format for a local user on a server computer. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### NetworkDelayMs - Specifies the extra time in milliseconds that the client computer waits to accommodate for network delay time. You can specify any value from 500 through 4294967295. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Password - Specifies the password for a local or a domain account. It cannot be NULL. - - The client computer can specify the credentials to use when creating a shell on a computer. The user name must be specified in the domain\user_name form for a domain user. The user name must be specified in the server_name\user_name format for a local user on a server computer. - - If you use this structure, then it should have both the user name and password fields specified. It can be used with Basic, Digest, Negotiate, or Kerberos authentication. The client must explicitly specify the credentials when either Basic or Digest authentication is used. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Plugin <> - WS-Management plug-ins are native dynamic link libraries (DLLs) that plug in to and extend the functionality of WS-Management . The WSW-Management Plug-in API provides functionality that enables a user to write plug-ins by implementing certain APIs for supported resource URIs and operations. After the plug-ins are configured for either the WS-Management (WinRM) service or for Internet Information Services (IIS), the plug-ins are loaded in the WS-Management host or in the IIS host, respectively. Remote requests are routed to these plug-in entry points to perform operations. - -#### Cmdlets supported: - -- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) - -- [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) - -### Port - Specifies the TCP port for which this listener is created. You can specify any value from 1 through 65535. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Resource - Specifies an endpoint that represents a distinct type of management operation or value. A service exposes one or more resources, and some resources can have more than one instance. A management resource is similar to a WMI class or to a database table, and an instance is similar to an instance of the class or to a row in the table. For example, the Win32_LogicalDisk class represents a resource. Win32_LogicalDisk="C:\\" is a specific instance of the resource. - - A Uniform Resource Identifier (URI) contains a prefix and a path to a resource. For example: - - http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk - - http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### ResourceURI - Specifies the Uniform Resource Identifier (URI) that identifies a specific type of resource, such as a disk or a process, on a computer. - - A URI consists of a prefix and a path to a resource. For example: - - http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk - - http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -### RootSDDL - Specifies the Security Descriptor Definition Language (SDDL) for the access control entry. This identifies the security settings that are used to authorize access to a specified resource URI. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### SDKVersion - Specifies the version of the WS-Management plug-in SDK. The only valid value is 1. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Shell - Specifies the process string for the custom shell. You can specify environment variables. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### ShellTimeout - Specifies the length of time before the shell times out due to inactivity. Specify the time-out value in milliseconds. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Subject - Specifies the entity that is identified by the certificate. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -### SupportsOptions - Specifies whether the plug-in supports the use of options, which are passed within the wsman:OptionSet header in a request message. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Transport - Specifies the transport to use to send and receive WS-Management protocol requests and responses. The value must be either HTTP or HTTPS. - - Note: The Transport value is set when creating a Listener. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -### TrustedHosts - List of remote computers that are connected to the local computer through a trusted network connection. Requests are allowed to be sent to computers specified in this list when using an authentication scheme and transport that does not allow the client to authenticate the service, such as Basic authentication over HTTP. - - If a server is specified in TrustedHosts, the client does not authenticate the server's identity, leaving it vulnerable to man-in-the-middle attacks. You should only specify hostnames when the network connection is safe from malicious users, such as in a Domain environment. - - The specified host names can be either Domain Name System (DNS) names or IP addresses. The following values are valid: - - -- Blank: No hosts are trusted. - - -- The asterisk "*" character: All hosts are trusted. - - A list of host name patterns separated by commas (,) The host name patterns must be formatted as follows: - - -- A string that starts with the wildcard character (*). The string must contain at least two characters. All the hosts that share the suffix are trusted. - - -- A string that ends with the wildcard character (*). The string must contain at least two characters. All the hosts that share the prefix are trusted. - - -- All NetBIOS names are trusted (for example, strings that do not contain a period). - - -- A string without the wildcard character (*): The host named by the string is trusted. - - Note: When the TrustedHosts value is set with the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet, the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet supports an additional parameter -Concatenate. The following example will append a new value (*.domain2.com) to the old value stored in TrustedHost: - - [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) .\TrustedHosts *.domain2.com -Concatenate -Force - -#### Cmdlets supported: - -- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### URI - Identifies the URI for which access is authorized based on the value of the Sddl parameter. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -### URLPrefix - A URL prefix on which to accept HTTP or HTTPS requests. This is a string containing only the characters a-z, A-Z, 9-0, underscore (_) and backslash (/). The string must not start with or end with a backslash (/). For example, if the computer name is SampleComputer, the WS-Management client would specify http://SampleMachine/URLPrefix in the destination address. - -#### Cmdlets supported: - -- [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### UserName - Specifies the user name for a local account or for a domain account. It cannot have a value of NULL. - - The client can specify the credentials to use when creating a shell on a computer. The user name must be specified in the domain\user_name format for a domain account. The user name must be specified in the server_name\user_name format for a local account on a server computer. - - If this structure is used, it must have both the username and password fields specified . It can be used with Basic, Digest, Negotiate, or Kerberos authentication. The client must explicitly specify the credentials when either Basic or Digest authentication is used. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### Value - Specifies the value of an initialization parameter, which is a plug-in-specific value that is used to specify configuration options. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### XMLRenderingType - Specifies the format in which XML is passed to plug-ins through the WSMAN_DATA object. The following are valid values: - - Text: Incoming XML data is contained in a WSMAN_DATA_TYPE_TEXT structure, which represents the XML as a PCWSTR memory buffer. - - XMLReader: Incoming XML data is contained in a WSMAN_DATA_TYPE_WS_XML_READER structure, which represents the XML as an XmlReader object, which is defined in the WebServices.h header file. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### xmlns - A string that specifies specifies a Uniform Resource Name (URN) that uniquely identifies the namespace. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### lang - A string that specifies a language, or a language-region with language and region separated by a hyphen. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### HTTP - Specifies the port that the client will use when HTTP is used. By default, HTTP uses port 80. You can specify any value from 1 through 65535. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### HTTPS - Specifies the port that the client will use when HTTPS is used. By default, HTTPS uses port 443. You can specify any value from 1 through 65535. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) - -### MaxShellRunTime - Note: This value is deprecated and the value is no longer used. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) - -### MaxShellRunTime - Note: This value is deprecated and the value is no longer used. - -#### Cmdlets supported: - -- [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) \ No newline at end of file diff --git a/reference/6/Microsoft.WSMan.Management/Providers/about_WSMan_Provider.md b/reference/6/Microsoft.WSMan.Management/Providers/about_WSMan_Provider.md new file mode 100644 index 000000000000..0b7591172eee --- /dev/null +++ b/reference/6/Microsoft.WSMan.Management/Providers/about_WSMan_Provider.md @@ -0,0 +1,562 @@ +--- +ms.date: 10/18/2018 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: WSMan Provider +online version: http://go.microsoft.com/fwlink/?LinkId=834980 +--- +# WSMan Provider + +## Provider name + +WSMan + +## Drives + +`WSMan:` + +## Short description + +Provides access to Web Services for Management (WS-Management) configuration +information. + +## Detailed description + +The WSMan provider for Windows PowerShell lets you add, change, clear, and +delete WS-Management configuration data on local or remote computers. + +The WSMan provider exposes a Windows PowerShell drive with a directory +structure that corresponds to a logical grouping of WS-Management configuration +settings. These groupings are known as containers. + +Beginning in Windows PowerShell 3.0, the WS-Management provider has been +updated to support new properties for session configurations, such as +**OutputBufferingMode**. The session configurations appear as items in the +Plugin directory of the `WSMan:` drive and the properties appear as items in +each session configuration. + +> [!NOTE] +> You can use commands in the `WSMan:` drive to change the values of the new +> properties. However, you cannot use the `WSMan:` drive in PowerShell 2.0 +> to change properties that are introduced in Windows PowerShell 3.0. +> Although no error is generated, the commands are not effective To change these +> settings, use the **WSMan** drive in Windows PowerShell 3.0. + +### Organization of the WSMan: Drive + +- **Client**: You can configure various aspects of the WS-Management client. The + configuration information is stored in the registry. + +- **Service**: You can configure various aspects of the WS-Management service. + The configuration information is stored in the registry. + > [!NOTE] + > Service configuration is sometimes referred to as Server configuration. + +- **Shell**: You can configure various aspects of the WS-Management shell, such + as the setting to allow remote shell access (**AllowRemoteShellAccess**) and + the maximum number of concurrent users allowed (**MaxConcurrentUsers**). + +- **Listener**: You can create and configure a listener. A listener is a + management service that implements the WS-Management protocol to send and to + receive messages. + +- **Plugin**: Plug-ins are loaded and used by the WS-Management service to + provide various functions. By default, PowerShell provides three plug-ins: + - The Event Forwarding plug-in. + - The Microsoft.PowerShell plug-in. + - The Windows Management Instrumentation (WMI) Provider plug-in. + These three plug-ins support event forwarding, configuration, and WMI access. + +- **ClientCertificate**: You can create and configure a client certificate. + A client certificate is used when the WS-Management client is configured to + use certificate authentication. + +### Directory Hierarchy of the WSMan Provider + +The directory hierarchy of the WSMan provider for the local computer is as +follows. + +``` +WSMan:\localhost +--- Client +--- Service +--- Shell +--- Listener +------ +--- Plugin +------ Event Forwarding Plugin +--------- InitializationParameters +--------- Resources +------------ Security +------ Microsoft.Powershell +--------- InitializationParameters +--------- Resources +------------ Security +------ WMI Provider +--------- InitializationParameters +--------- Resources +------------ Security +--- ClientCertificate +``` + +The directory hierarchy of the WSMan provider for a remote computer is the same +as a local computer. However, in order to access the configuration settings of +a remote computer, you need to make a connection to the remote computer using +[Connect-WSMan](../Connect-WSMan.md). Once a connection is made to a remote +computer, the name of the remote computer shows up in the provider. + +``` +WSMan:\ +``` + +## Navigating the WSMan: Drive + +This command uses the `Set-Location` cmdlet to change the current location to +the `WSMan:` drive. + +```powershell +Set-Location WSMan: +``` + +To return to a file system drive, type the drive name. For example, type. + +```powershell +Set-Location C: +``` + +### Navigating to a remote system store location + +This command uses the `Set-Location` command to change the current location +to the root location in the remote system store location. Use a backslash `\` +or forward slash `/` to indicate a level of the `WSMan:` drive. + +```powershell +Set-Location -Path WSMan:\SERVER01 +``` + +> [!NOTE] +> The above command assume that a connection to the remote system already +> exists. + +## Displaying the Contents of the WSMan: Drive + +This command uses the `Get-Childitem` cmdlet to display the WS-Management stores +in the Localhost store location. + +```powershell +Get-ChildItem -path WSMan:\Localhost +``` + +If you are in the `WSMan:` drive, you can omit the drive name. + +This command uses the `Get-Childitem` cmdlet to display the WS-Management +stores in the remote computer "SERVER01" store location. + +```powershell +Get-ChildItem -path WSMan:\SERVER01 +``` + +> [!NOTE] +> The above command assume that a connection to the remote system already +> exists. + +## Setting the value of items in the WSMAN: drive + +You can use the `Set-Item` cmdlet to change configuration settings in the +`WSMAN` drive. The following example sets the **TrustedHosts** value to +accept all hosts with the suffix "contoso.com". + +```powershell +# You do not need to specify the -Path parameter name when using Set-Item. +PS WSMAN:\localhost\Client> Set-Item .\TrustedHosts -Value "*.contoso.com" +``` + +The `Set-Item` cmdlet supports an additional parameter `-Concatenate` that +appends a value instead of changing it. The following example will append a +new value "*.domain2.com" to the old value stored in `TrustedHost:` + +```powershell +Set-Item WSMAN:\localhost\Client\TrustedHosts *.domain2.com -Concatenate +``` + +## Creating items in the WSMAN: drive + +### Creating a new listener + +The `New-Item` cmdlet creates items within a provider drive. Each provider +has different item types that you can create. In the `WSMAN:` drive, you can +create *Listeners* which you configure to receive and respond to remote +requests. The following command creates a new HTTP listener using the `New-Item` +cmdlet. + +```powershell +New-Item -Path WSMan:\localhost\Listener -Address * -Transport HTTP -force +``` + +### Creating a new plug-in + +This command creates (registers) a plug-in for the WS-Management service. + +```powershell +New-Item -Path WSMan:\localhost\Plugin ` + -Plugin TestPlugin ` + -FileName %systemroot%\system32\WsmWmiPl.dll ` + -Resource http://schemas.dmtf.org/wbem/wscim/2/cim-schema ` + -SDKVersion 1 ` + -Capability "Get","Put","Invoke","Enumerate" ` + -XMLRenderingType text +``` + +### Creating a new resource entry + +This command creates a resource entry in the Resources directory of +a TestPlugin. This command assumes that a TestPlugin has been created using +a separate command. + +```powershell +New-Item -Path WSMan:\localhost\Plugin\TestPlugin\Resources ` + -ResourceUri http://schemas.dmtf.org/wbem/wscim/3/cim-schema ` + -Capability "Enumerate" + +``` + +### Creating a new security entry for a resource + +This command creates a security entry in the Security directory of +Resource_5967683 (a specific resource). This command assumes that the resource +entry has been created using a separate command. + +```powershell +$path = "WSMan:\localhost\Plugin\TestPlugin\Resources\Resource_5967683" +New-Item -Path $path\Security ` + -Sddl "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;SA;GWGX;;;WD)" +``` + +### Creating a new Client Certificate + +This command creates **ClientCertificate** entry that can be used by the +WS-Management client. The new **ClientCertificate** will show up under the +**ClientCertificate** directory as "ClientCertificate_1234567890". All of the +parameters are mandatory. The **Issuer** needs to be thumbprint of the issuers +certificate. + +```powershell +$cred = Get-Credential +New-Item -Path WSMan:\localhost\ClientCertificate ` + -Issuer 1b3fd224d66c6413fe20d21e38b304226d192dfe ` + -URI wmicimv2/* ` + -Credential $cred; +``` + +### Creating a new Initialization Parameter + +This command creates an Initialization parameter named "testparametername" +in the "InitializationParameters" directory. This command assumes that the +"TestPlugin" has been created using a separate command. + +```powershell +New-Item -Path WSMan:\localhost\Plugin\TestPlugin\InitializationParameters ` + -ParamName testparametername ` + -ParamValue testparametervalue +``` + +## Dynamic parameters + +Dynamic parameters are cmdlet parameters that are added by a Windows PowerShell +provider and are available only when the cmdlet is being used in the +provider-enabled drive. + +### Address \ + +Specifies the address for which this listener was created. The value can be one +of the following: + +- The literal string "*". (The wildcard character (`*`) makes the command bind + all the IP addresses on all the network adapters.) +- The literal string "IP:" followed by a valid IP address in either IPv4 + dotted-decimal format or in IPv6 cloned-hexadecimal format. +- The literal string "MAC:" followed by the MAC address of an adapter. + For example: MAC:32-a3-58-90-be-cc. + +> [!NOTE] +> The Address value is set when creating a Listener. + +#### Cmdlets supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Capability \ + +When working with *Plug-ins* this parameter specifies an operation that is +supported on this Uniform Resource Identifier (URI). You have to create one +entry for each type of operation that the URI supports. You can specify +any valid attributes for a given operation, if the operation supports it. + +These attributes include **SupportsFiltering** and **SupportsFragment**. + +- **Create**: Create operations are supported on the URI. + - The **SupportFragment** attribute is used if the Create operation + supports the concept. + - The **SupportFiltering** attribute is NOT valid for Create operations and + should be set to "False". + > [!NOTE] + > This operation is not valid for a URI if Shell operations are also + > supported. +- **Delete**: Delete operations are supported on the URI. + - The **SupportFragment** attribute is used if the Delete operation supports + the concept. + - The **SupportFiltering** attribute is NOT valid for Delete operations and + should be set to "False". + > [!NOTE] + > This operation is not valid for a URI if Shell operations are also + > supported. +- **Enumerate**: Enumerate operations are supported on the URI. + - The **SupportFragment** attribute is NOT supported for Enumerate operations + and should be set to False. + - The **SupportFiltering** attribute is valid, and if the plug-in supports + filtering, this attribute should be set to "True". + > [!NOTE] + > This operation is not valid for a URI if Shell operations are also + > supported. +- **Get**: Get operations are supported on the URI. + - The **SupportFragment** attribute is used if the Get operation supports the + concept. + - The **SupportFiltering** attribute is NOT valid for Get operations and + should be set to "False". + > [!NOTE] + > This operation is not valid for a URI if Shell operations are also + > supported. +- **Invoke**: Invoke operations are supported on the URI. + - The **SupportFragment** attribute is not supported for Invoke operations + and should be set to False. + - The **SupportFiltering** attribute is not valid and should be set to + "False". + > [!NOTE] + > This operation is not valid for a URI if Shell operations are also + > supported. +- **Put**: Put operations are supported on the URI. + - The **SupportFragment** attribute is used if the Put operation supports the + concept. + - The **SupportFiltering** attribute is not valid for Put operations and + should be set to "False". + > [!NOTE] + > This operation is not valid for a URI if Shell operations are also + > supported. +- **Subscribe**: Subscribe operations are supported on the URI. + - The **SupportFragment** attribute is not supported for Subscribe operations + and should be set to False. + - The **SupportFiltering** attribute is not valid for Subscribe operations and + should be set to "False". + > [!NOTE] + > This operation is not valid for a URI if Shell operations are also + > supported. +- **Shell**: Shell operations are supported on the URI. + - The **SupportFragment** attribute is not supported for Shell operations and + should be set to "False". + - The **SupportFiltering** attribute is not valid for Shell operations and + should be set to "False". + > [!NOTE] + > This operation is not valid for a URI if ANY other operation is also + > supported. + > [!NOTE] + > If a Shell operation is configured for a URI, Get, Put, Create, Delete, + > Invoke, and Enumerate operations are processed internally within the + > WS-Management (WinRM) service to manage shells. As a result, the plug-in + > cannot handle the operations. + +#### Cmdlets supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### CertificateThumbprint \ + +Specifies the thumbprint of the service certificate. + +This value represents the string of two-digit hexadecimal values in the +Thumbprint field of the certificate. It specifies the digital public key +certificate (X509) of a user account that has permission to perform this +action. Certificates are used in client certificate-based authentication. They +can be mapped only to local user accounts, and they do not work with domain +accounts. To get a certificate thumbprint, use the `Get-Item` or `Get-ChildItem` +cmdlets in the Windows PowerShell `Cert:` drive. + +#### Cmdlets supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Enabled \ + +Specifies whether the listener is enabled or disabled. The default is True. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### FileName (Plugin) \ + +Specifies the file name of the operations plug-in. Any environment variables +that are put in this entry will be expanded in the users' context when a +request is received. Because each user could have a different version of the +same environment variable, each user could have a different plug-in. This entry +cannot be blank and must point to a valid plug-in. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### HostName \ + +Specifies the host name of the computer on which the WS-Management (WinRM) +service is running. + +The value must be a fully qualified domain name, an IPv4 or IPv6 literal +string, or a wildcard character. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Issuer \ + +Specifies the name of the certification authority that issued the certificate. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Plugin \<\> WS-Management plug-ins are native dynamic link libraries (DLLs) + +that plug in to and extend the functionality of WS-Management . The +WSW-Management Plug-in API provides functionality that enables a user to write +plug-ins by implementing certain APIs for supported resource URIs and +operations. After the plug-ins are configured for either the WS-Management +(WinRM) service or for Internet Information Services (IIS), the plug-ins are +loaded in the WS-Management host or in the IIS host, respectively. Remote +requests are routed to these plug-in entry points to perform operations. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Port \ + +Specifies the TCP port for which this listener is created. You can specify any +value from 1 through 65535. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Resource \ + +Specifies an endpoint that represents a distinct type of management operation +or value. A service exposes one or more resources, and some resources can have +more than one instance. A management resource is similar to a WMI class or to a +database table, and an instance is similar to an instance of the class or to a +row in the table. For example, the **Win32_LogicalDisk** class represents a +resource. `Win32_LogicalDisk="C:\\"` is a specific instance of the resource. + +A Uniform Resource Identifier (URI) contains a prefix and a path to a resource. +For example: + +http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk + +http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Resource \ + +Specifies the Uniform Resource Identifier (URI) that identifies a specific type +of resource, such as a disk or a process, on a computer. + +A URI consists of a prefix and a path to a resource. For example: + +http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk + +http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### SDKVersion \ + +Specifies the version of the WS-Management plug-in SDK. The only valid value is +1. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Subject \ + +Specifies the entity that is identified by the certificate. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Transport \ + +Specifies the transport to use to send and receive WS-Management protocol +requests and responses. The value must be either HTTP or HTTPS. + +Note: The Transport value is set when creating a Listener. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### URI \ + +Identifies the URI for which access is authorized based on the value of the +Sddl parameter. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### URLPrefix \ + +A URL prefix on which to accept HTTP or HTTPS requests. This is a string +containing only the characters `[a-z]`, `[A-Z]`, `[9-0]`, +underscore (`_`) and backslash (`/`). The string must not start with or end +with a backslash (`/`). For example, if the computer name is "SampleComputer", +the WS-Management client would specify "http://SampleMachine/URLPrefix" +in the destination address. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### Value \ + +Specifies the value of an initialization parameter, which is a plug-in-specific +value that is used to specify configuration options. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +### XMLRenderingType \ + +Specifies the format in which XML is passed to plug-ins through the +**WSMAN_DATA** object. The following are valid values: + +- Text: Incoming XML data is contained in a **WSMAN_DATA_TYPE_TEXT** structure, + which represents the XML as a **PCWSTR** memory buffer. +- XMLReader: Incoming XML data is contained in a + **WSMAN_DATA_TYPE_WS_XML_READER** structure, which represents the XML as an + **XmlReader** object, which is defined in the "WebServices.h" header file. + +#### Cmdlets Supported + +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) + +## See also + +[about_Providers](../../Microsoft.PowerShell.Core/About/about_Providers.md) \ No newline at end of file