diff --git a/reference/3.0/Microsoft.PowerShell.Security/Get-Acl.md b/reference/3.0/Microsoft.PowerShell.Security/Get-Acl.md index 6497bc73cd57..ad13a3817d34 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Get-Acl.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Get-Acl.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,47 +7,57 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113305 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Get-Acl --- - # Get-Acl + ## SYNOPSIS + Gets the security descriptor for a resource, such as a file or registry key. + ## SYNTAX ### ByPath (Default) + ``` Get-Acl [[-Path] ] [-Audit] [-AllCentralAccessPolicies] [-Filter ] [-Include ] [-Exclude ] [-UseTransaction] [] ``` ### ByInputObject + ``` Get-Acl -InputObject [-Audit] [-AllCentralAccessPolicies] [-Filter ] [-Include ] [-Exclude ] [-UseTransaction] [] ``` ### ByLiteralPath + ``` Get-Acl [-LiteralPath ] [-Audit] [-AllCentralAccessPolicies] [-Filter ] [-Include ] [-Exclude ] [-UseTransaction] [] ``` ## DESCRIPTION + The **Get-Acl** cmdlet gets objects that represent the security descriptor of a file or resource. The security descriptor contains the access control lists (ACLs) of the resource. The ACL specifies the permissions that users and user groups have to access the resource. Beginning in Windows PowerShell 3.0, you can use the **InputObject** parameter of **Get-Acl** to get the security descriptor of objects that do not have a path. + ## EXAMPLES ### Example 1 -``` -PS C:\> Get-Acl C:\Windows + +```powershell +Get-Acl C:\Windows ``` This command gets the security descriptor of the C:Windows directory. + ### Example 2 -``` -PS C:\> Get-Acl C:\Windows\k*.log | Format-List -Property PSPath, Sddl + +```powershell +Get-Acl C:\Windows\k*.log | Format-List -Property PSPath, Sddl ``` This command gets the Windows PowerShell path and SDDL for all of the .log files in the C:\Windows directory whose names begin with "k." @@ -60,32 +70,40 @@ Lists are often used in Windows PowerShell, because long values appear truncated The **SDDL** values are valuable to system administrators, because they are simple text strings that contain all of the information in the security descriptor. As such, they are easy to pass and store, and they can be parsed when needed. + ### Example 3 -``` -PS C:\> Get-Acl C:/Windows/k*.log -Audit | Foreach-Object { $_.Audit.Count } + +```powershell +Get-Acl C:/Windows/k*.log -Audit | ForEach-Object { $_.Audit.Count } ``` This command gets the security descriptors of the .log files in the C:\Windows directory whose names begin with "k." It uses the **Audit** parameter to get the audit records from the SACL in the security descriptor. Then it uses theForEach-Object cmdlet to count the number of audit records associated with each file. The result is a list of numbers representing the number of audit records for each log file. + ### Example 4 -``` -PS C:\> Get-Acl -Path HKLM:\System\CurrentControlSet\Control | Format-List + +```powershell +Get-Acl -Path HKLM:\System\CurrentControlSet\Control | Format-List ``` This command uses the **Get-Acl** cmdlet to get the security descriptor of the Control subkey (HKLM\SYSTEM\CurrentControlSet\Control) of the registry. The **Path** parameter specifies the Control subkey. The pipeline operator (|) passes the security descriptor that **Get-Ac**l gets to the Format-List command, which formats the properties of the security descriptor as a list so that they are easy to read. + ### Example 5 -``` -PS C:\> Get-Acl -InputObject (Get-StorageSubsystem -Name S087) + +```powershell +Get-Acl -InputObject (Get-StorageSubSystem -Name S087) ``` This command uses the **InputObject** parameter of **Get-Acl** to get the security descriptor of a storage subsystem object. + ## PARAMETERS ### -Audit + Gets the audit data for the security descriptor from the system access control list (SACL). ```yaml @@ -101,6 +119,7 @@ Accept wildcard characters: False ``` ### -Exclude + Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". @@ -119,6 +138,7 @@ 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. @@ -137,6 +157,7 @@ Accept wildcard characters: True ``` ### -Include + Gets only the specified items. The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". @@ -155,6 +176,7 @@ Accept wildcard characters: True ``` ### -Path + Specifies the path to a resource. **Get-Acl** gets the security descriptor of the resource indicated by the path. Wildcards are permitted. @@ -175,10 +197,11 @@ Accept wildcard characters: True ``` ### -AllCentralAccessPolicies + Gets information about all central access policies that are enabled on the computer. Beginning in Windows Server® 2012, administrators can use Active Directory and Group Policy to set central access policies for users and groups. -For more information, see [Dynamic Access Control: Scenario Overview](http://go.microsoft.com/fwlink/?LinkId=238408). +For more information, see [Dynamic Access Control: Scenario Overview](/windows-server/identity/solution-guides/dynamic-access-control--scenario-overview). This parameter is introduced in Windows PowerShell 3.0. @@ -195,6 +218,7 @@ Accept wildcard characters: False ``` ### -InputObject + Gets the security descriptor for the specified object. Enter a variable that contains the object or a command that gets the object. @@ -216,6 +240,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies the path to a resource. Unlike **Path**, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcards. @@ -237,6 +262,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 about_Transactions. @@ -254,18 +280,25 @@ 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). + ## INPUTS ### System.String + You can pipe a string that contains a path to Get-Acl. + ## OUTPUTS ### System.Security.AccessControl + **Get-Acl** returns an object that represents the ACLs that it gets. The object type depends upon the ACL type. + ## NOTES -* By default, **Get-Acl** displays the Windows PowerShell path to the resource (\::\), the owner of the resource, and "Access", a list (array) of the access control entries in the discretionary access control list (DACL) for the resource. The DACL list is controlled by the resource owner. + +- By default, **Get-Acl** displays the Windows PowerShell path to the resource (\::\), the owner of the resource, and "Access", a list (array) of the access control entries in the discretionary access control list (DACL) for the resource. The DACL list is controlled by the resource owner. When you format the result as a list, ("`Get-Acl | Format-List`"), in addition to the path, owner, and access list, Windows PowerShell displays the following properties and property values: @@ -278,8 +311,9 @@ The SACL specifies the types of access attempts for which Windows generates audi Windows PowerShell uses the GetSddlForm method of security descriptors to get this data. Because **Get-Acl** is supported by the file system and registry providers, you can use **Get-Acl** to view the ACL of file system objects, such as files and directories, and registry objects, such as registry keys and entries. + + -* ## RELATED LINKS [Set-Acl](Set-Acl.md) \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md b/reference/3.0/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md index cf559afcffe3..b287e7ecdb3e 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,44 +7,55 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113307 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Get-AuthenticodeSignature --- - # Get-AuthenticodeSignature + ## SYNOPSIS + Gets information about the Authenticode signature in a file. + ## SYNTAX ### ByPath (Default) + ``` Get-AuthenticodeSignature [-FilePath] [] ``` ### ByLiteralPath + ``` Get-AuthenticodeSignature -LiteralPath [] ``` ## DESCRIPTION + The Get-AuthenticodeSignature cmdlet gets information about the Authenticode signature in a file. If the file is not signed, the information is retrieved, but the fields are blank. + ## EXAMPLES ### Example 1 -``` -PS C:\> get-AuthenticodeSignature -filepath C:\Test\NewScript.ps1 + +```powershell +Get-AuthenticodeSignature -FilePath C:\Test\NewScript.ps1 ``` This command gets information about the Authenticode signature in the NewScript.ps1 file. It uses the FilePath parameter to specify the file. + ### Example 2 -``` -PS C:\> get-authenticodesignature test.ps1, test1.ps1, sign-file.ps1, makexml.ps1 + +```powershell +Get-AuthenticodeSignature test.ps1, test1.ps1, sign-file.ps1, makexml.ps1 ``` This command gets information about the Authenticode signature in the four files listed at the command line. In this command, the name of the FilePath parameter, which is optional, is omitted. + ### Example 3 -``` -PS C:\> get-childitem $pshome\*.* | foreach-object {Get-AuthenticodeSignature $_} | where {$_.status -eq "Valid"} + +```powershell +Get-ChildItem $pshome\*.* | ForEach-Object {Get-AuthenticodeSignature $_} | where {$_.status -eq "Valid"} ``` This command lists all of the files in the $pshome directory that have a valid Authenticode signature. @@ -56,9 +67,11 @@ It uses a pattern of *.* to exclude directories (although it also excludes files The command uses a pipeline operator (|) to send the files in $pshome to the Foreach-Object cmdlet, where Get-AuthenticodeSignature is called for each file. The results of the Get-AuthenticodeSignature command are sent to a Where-Object command that selects only the signature objects with a status of "Valid". + ## PARAMETERS ### -FilePath + Specifies the path to the file being examined. Wildcards are permitted, but they must lead to a single file. The parameter name ("FilePath") is optional. @@ -76,6 +89,7 @@ Accept wildcard characters: True ``` ### -LiteralPath + Specifies the path to the file being examined. Unlike **FilePath**, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcards. @@ -95,19 +109,25 @@ 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). + ## INPUTS ### System.String + You can pipe a string that contains a file path to Get-AuthenticodeSignature. + ## OUTPUTS ### System.Management.Automation.Signature + Get-AuthenticodeSignature returns a signature object for each signature that it gets. + ## NOTES -* For information about Authenticode signatures in Windows PowerShell, see about_Signing. -* +- For information about Authenticode signatures in Windows PowerShell, see about_Signing. + ## RELATED LINKS [Get-ExecutionPolicy](Get-ExecutionPolicy.md) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Get-Credential.md b/reference/3.0/Microsoft.PowerShell.Security/Get-Credential.md index a411b3ac3342..b7ea3efc41d2 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Get-Credential.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Get-Credential.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,23 +7,28 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113311 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Get-Credential --- - # Get-Credential + ## SYNOPSIS + Gets a credential object based on a user name and password. + ## SYNTAX ### CredentialSet (Default) + ``` Get-Credential [-Credential] [] ``` ### MessageSet + ``` Get-Credential -Message [[-UserName] ] [] ``` ## DESCRIPTION + The **Get-Credential** cmdlet creates a credential object for a specified user name and password. You can use the credential object in security operations. @@ -33,11 +38,13 @@ The **Get-Credential** cmdlet prompts the user for a password or a user name and By default, an authentication dialog box appears to prompt the user. However, in some host programs, such as the Windows PowerShell console, you can prompt the user at the command line by changing a registry entry. For more information about this registry entry, see the notes and examples. + ## EXAMPLES ### Example 1 -``` -PS C:\> $c = Get-Credential + +```powershell +$c = Get-Credential ``` This command gets a credential object and saves it in the $c variable. @@ -47,10 +54,12 @@ When you enter the requested information, the cmdlet creates a **PSCredential** You can use the object as input to cmdlets that request user authentication, such as those with a **Credential** parameter. However, some providers that are installed with Windows PowerShell do not support the **Credential** parameter. + ### Example 2 -``` -PS C:\> $c = Get-Credential -PS C:\> Get-WmiObject Win32_DiskDrive -ComputerName Server01 -Credential $c + +```powershell +$c = Get-Credential +Get-WmiObject Win32_DiskDrive -ComputerName Server01 -Credential $c ``` These commands use a credential object that the **Get-Credential** cmdlet returns to authenticate a user on a remote computer so they can use Windows Management Instrumentation (WMI) to manage the computer. @@ -58,19 +67,23 @@ These commands use a credential object that the **Get-Credential** cmdlet return The first command gets a credential object and saves it in the $c variable. The second command uses the credential object in a Get-WmiObject command. This command gets information about the disk drives on the Server01 computer. + ### Example 3 -``` -PS C:\> Get-WmiObject Win32_BIOS -ComputerName Server01 -Credential (Get-Credential -Credential Domain01\User01) + +```powershell +Get-WmiObject Win32_BIOS -ComputerName Server01 -Credential (Get-Credential -Credential Domain01\User01) ``` This command shows how to include a **Get-Credential** command in a **Get-WmiObject** command. This command uses the Get-WmiObject cmdlet to get information about the BIOS on the Server01 computer. It uses the **Credential** parameter to authenticate the user, Domain01\User01, and a **Get-Credential** command as the value of the **Credential** parameter. + ### Example 4 + ``` -PS C:\> $c = Get-Credential -credential User01 -PS C:\> $c.Username +PS> $c = Get-Credential -credential User01 +PS> $c.Username \User01 ``` @@ -80,9 +93,11 @@ It demonstrates that Get-Credential inserts a backslash before the user name. The first command gets a credential with the user name User01 and stores it in the $c variable. The second command displays the value of the **Username** property of the resulting credential object. + ### Example 5 -``` -PS C:\> $Credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "", "NetBiosUserName") + +```powershell +$Credential = $host.ui.PromptForCredential("Need credentials", "Please enter your user name and password.", "", "NetBiosUserName") ``` This command uses the **PromptForCredential** method to prompt the user for their user name and password. @@ -90,9 +105,11 @@ The command saves the resulting credentials in the $Credential variable. The **PromptForCredential** method is an alternative to using the **Get-Credential** cmdlet. When you use **PromptForCredential**, you can specify the caption, messages, and user name that appear in the message box. + ### Example 6 -``` -PS C:\> Set-ItemProperty "HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds" -Name ConsolePrompting -Value $true + +```powershell +Set-ItemProperty "HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds" -Name ConsolePrompting -Value $true ``` This example shows how to modify the registry so that the user is prompted at the command line, instead of by using a dialog box. @@ -104,23 +121,27 @@ To use a dialog box for prompting, set the value of the ConsolePrompting to fals The ConsolePrompting registry entry works in some host programs, such as the Windows PowerShell console. It might not work in all host programs. + ### Example 7 + ``` The first command saves the user account name in the $User parameter. The value must have the "Domain\User" or "ComputerName\User" format. -PS C:\> $User = "Domain01\User01" +PS> $User = "Domain01\User01" The second command uses the ConvertTo-SecureString cmdlet to create a secure string from a plain text password. The command uses the **AsPlainText** parameter to indicate that the string is plain text and the **Force** parameter to confirm that you understand the risks of using plain text. -PS C:\> $PWord = ConvertTo-SecureString -String "P@sSwOrd" -AsPlainText -Force +PS> $PWord = ConvertTo-SecureString -String "P@sSwOrd" -AsPlainText -Force The third command uses the New-Object cmdlet to create a **PSCredential** object from the values in the $User and $PWord variables. -PS C:\> $Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWord +PS> $Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWord ``` This example shows how to create a credential object that is identical to the object that **Get-Credential** returns without prompting the user. This method requires a plain text password, which might violate the security standards in some enterprises. + ### Example 8 + ``` -PS C:\> Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUsers +PS> Get-Credential -Message "Credential are required for access to the \\Server1\Scripts file share." -User Server01\PowerUsers Windows PowerShell Credential Request Credential are required for access to the \\Server1\Scripts file share. Password for user ntdev\juneb: @@ -129,9 +150,11 @@ Password for user ntdev\juneb: This command uses the **Message** and **UserName** parameters of the **Get-Credential** cmdlet. This command format is designed for shared scripts and functions. In this case, the message tells the user why credentials are needed and gives them confidence that the request is legitimate. + ### Example 9 + ``` -PS C:\> Invoke-Command -ComputerName Server01 {Get-Credential Domain01\User02} +PS> Invoke-Command -ComputerName Server01 {Get-Credential Domain01\User02} Windows PowerShell Credential Request : Windows PowerShell Credential Request Warning: This credential is being requested by a script or application on the SERVER01 remote computer. Enter your credentials only if you @@ -152,9 +175,11 @@ Password : System.Security.SecureString This command gets a credential from the Server01 remote computer. The command uses the Invoke-Command cmdlet to run a **Get-Credential** command on the remote computer. The output shows the remote security message that **Get-Credential** includes in the authentication prompt. + ## PARAMETERS ### -Credential + Specifies a user name for the credential, such as "User01" or "Domain01\User01". The parameter name ("Credential") is optional. @@ -177,6 +202,7 @@ Accept wildcard characters: False ``` ### -Message + Specifies a message that appears in the authentication prompt. This parameter is designed for use in a function or script. @@ -197,6 +223,7 @@ Accept wildcard characters: False ``` ### -UserName + Specifies a user name. The authentication prompt requests a password for the user name. By default, the user name is blank and the authentication prompt requests both a user name and password. @@ -220,22 +247,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). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### System.Management.Automation.PSCredential + Get-Credential returns a credential object. + ## NOTES -* You can use the **PSCredential** object that **Get-Credential** creates in cmdlets that request user authentication, such as those with a **Credential** parameter. -* By default, the authentication prompt appears in a dialog box. To display the authentication prompt at the command line, add the **ConsolePrompting** registry entry (HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\ConsolePrompting) and set its value to True. If the **ConsolePrompting** registry entry does not exist or if its value is False, the authentication prompt appears in a dialog box. For instructions, see the examples. + +- You can use the **PSCredential** object that **Get-Credential** creates in cmdlets that request user authentication, such as those with a **Credential** parameter. +- By default, the authentication prompt appears in a dialog box. To display the authentication prompt at the command line, add the **ConsolePrompting** registry entry (HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\ConsolePrompting) and set its value to True. If the **ConsolePrompting** registry entry does not exist or if its value is False, the authentication prompt appears in a dialog box. For instructions, see the examples. The **ConsolePrompting** registry entry works in the Windows PowerShell console, but it does not work in all host programs. For example, it has no effect in the Windows PowerShell Integrated Scripting Environment (ISE). For information about the effect of the **ConsolePrompting** registry entry, see the help topics for the host program. -* The **Credential** parameter is not supported by all providers that are installed with Windows PowerShell. Beginning in Windows PowerShell 3.0, it is supported on selected cmdlet, such as the Get-WmiObject and New-PSDrive cmdlets. +- The **Credential** parameter is not supported by all providers that are installed with Windows PowerShell. Beginning in Windows PowerShell 3.0, it is supported on selected cmdlet, such as the Get-WmiObject and New-PSDrive cmdlets. ## RELATED LINKS \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md b/reference/3.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md index 499a36f55997..50e8edf333b6 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Get-ExecutionPolicy.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113315 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Get-ExecutionPolicy --- - # Get-ExecutionPolicy + ## SYNOPSIS + Gets the execution policies for the current session. + ## SYNTAX ``` @@ -18,6 +20,7 @@ Get-ExecutionPolicy [[-Scope] ] [-List] [ Get-ExecutionPolicy + +``` +PS> Get-ExecutionPolicy Restricted ``` This command gets the current execution policy for the computer. + ### Example 2 -```powershell -PS C:\> Set-ExecutionPolicy RemoteSigned -PS C:\> Get-ExecutionPolicy + +``` +PS> Set-ExecutionPolicy RemoteSigned +PS> Get-ExecutionPolicy RemoteSigned ``` These commands set a new user preference for the execution policy and then display the effective execution policy. The commands are separated by a semicolon (;). In this example, because there is no Group Policy setting, the user preference is the effective policy for the computer. + ### Example 3 -```powershell -PS C:\> Get-ExecutionPolicy -List + +``` +PS> Get-ExecutionPolicy -List Scope ExecutionPolicy ----- --------------- @@ -58,7 +67,7 @@ Process Undefined CurrentUser AllSigned LocalMachine RemoteSigned -PS C:\> Get-ExecutionPolicy +PS> Get-ExecutionPolicy AllSigned ``` @@ -70,13 +79,14 @@ The policies are listed in precedence order. The second command gets only the effective execution policy, which is the one set in the CurrentUser scope. ### Example 4 -```powershell + +``` The first command uses the **Get-ExecutionPolicy** cmdlet to get the effective execution policy in the current session. -PS C:\> Get-ExecutionPolicy +PS> Get-ExecutionPolicy RemoteSigned The second command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is **RemoteSigned**. The **RemoteSigned** policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 +PS> .\Start-ActivityTracker.ps1 .\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 @@ -87,20 +97,22 @@ At line:1 char:1 The third command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path Start-ActivityTracker.ps1 +PS> Unblock-File -Path Start-ActivityTracker.ps1 This command shows the effect of the **Unblock-File** command. The command does not change the execution policy. However, it unblocks the script so it will run in Windows PowerShell. -PS C:\> Get-ExecutionPolicy +PS> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 +PS> Start-ActivityTracker.ps1 Task 1: ``` This example shows the effect of the **RemoteSigned** execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. + ## PARAMETERS ### -List + Gets all execution policy values for the session listed in precedence order. By default, **Get-ExecutionPolicy** gets only the effective execution policy. @@ -117,6 +129,7 @@ Accept wildcard characters: False ``` ### -Scope + Gets the execution policy in the specified scope. By default, **Get-ExecutionPolicy** gets the effective execution policy for the current session. @@ -141,22 +154,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). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### Microsoft.PowerShell.ExecutionPolicy ## NOTES -* The execution policy is part of the security strategy of Windows PowerShell. It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. + +- The execution policy is part of the security strategy of Windows PowerShell. It determines whether you can load configuration files (including your Windows PowerShell profile) and run scripts, and it determines which scripts, if any, must be digitally signed before they will run. The effective execution policy is determined by the policies that you set by using the Set-ExecutionPolicy cmdlet and the "Turn on Script Execution" group policies for computers and users. The precedence order is Computer Group Policy \> User Group Policy \> Process (session) execution policy \> User execution policy \> Computer execution policy. For more information about Windows PowerShell execution policy, including definitions of the Windows PowerShell policies, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). + ## RELATED LINKS [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Get-PfxCertificate.md b/reference/3.0/Microsoft.PowerShell.Security/Get-PfxCertificate.md index 649740870c23..72f186291e1a 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Get-PfxCertificate.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Get-PfxCertificate.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,30 +7,37 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113323 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Get-PfxCertificate --- - # Get-PfxCertificate + ## SYNOPSIS + Gets information about .pfx certificate files on the computer. + ## SYNTAX ### ByPath (Default) + ``` Get-PfxCertificate [-FilePath] [] ``` ### ByLiteralPath + ``` Get-PfxCertificate -LiteralPath [] ``` ## DESCRIPTION + The Get-PfxCertificate cmdlet gets an object representing each specified .pfx certificate file. A .pfx file includes both the certificate and a private key. + ## EXAMPLES ### Example 1 + ``` -PS C:\> get-pfxcertificate -filepath C:\windows\system32\Test.pfx +PS> get-pfxcertificate -filepath C:\windows\system32\Test.pfx Password: ****** Signer Certificate: Matt Berg (Self Certificate) Time Certificate: @@ -39,18 +46,22 @@ Path: C:\windows\system32\zap.pfx ``` This command gets information about the Test.pfx certificate on the system. + ### Example 2 -``` -PS C:\> invoke-command -computername Server01 -scriptblock {get-pfxcertificate -filepath C:\Text\TestNoPassword.pfx} -authentication CredSSP + +```powershell +Invoke-Command -ComputerName Server01 -ScriptBlock {Get-PfxCertificate -FilePath C:\Text\TestNoPassword.pfx} -Authentication CredSSP ``` This command gets a .pfx certificate file from the Server01 remote computer. It uses the Invoke-Command to run a Get-PfxCertificate command remotely. When the .pfx certificate file is not password-protected, the value of the Authentication parameter of Invoke-Command must be "CredSSP". + ## PARAMETERS ### -FilePath + The full path to the .pfx file of the secured file. The parameter name ("FilePath") is optional. @@ -67,6 +78,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + The full path to the .pfx file of the secured file. Unlike **FilePath**, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcards. @@ -86,19 +98,25 @@ 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). + ## INPUTS ### System.String + You can pipe a string that contains a file path to Get-PfxCertificate. + ## OUTPUTS ### System.Security.Cryptography.X509Certificates.X509Certificate2 + Get-PfxCertificate returns an object for each certificate that it gets. + ## NOTES -* When using the Invoke-Command cmdlet to run a Get-PfxCertificate command remotely, and the .pfx certificate file is not password protected, the value of the Authentication parameter of Invoke-Command must be "CredSSP". -* +- When using the Invoke-Command cmdlet to run a Get-PfxCertificate command remotely, and the .pfx certificate file is not password protected, the value of the Authentication parameter of Invoke-Command must be "CredSSP". + ## RELATED LINKS [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Microsoft.PowerShell.Security.md b/reference/3.0/Microsoft.PowerShell.Security/Microsoft.PowerShell.Security.md index 1e1765340d53..15c1dea3916f 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Microsoft.PowerShell.Security.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Microsoft.PowerShell.Security.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -9,47 +9,59 @@ Module Guid: a94c8c7e-9810-47c0-b8af-65089c13a35a title: Microsoft.PowerShell.Security Module Name: Microsoft.PowerShell.Security --- - # Microsoft.PowerShell.Security Module + ## Description + This section contains the help topics for the cmdlets that are installed with Windows PowerShell Microsoft.PowerShell.Security module. The Security module contains cmdlets and providers that manage the basic security features of Windows. ## Microsoft.PowerShell.Security Cmdlets + ### [ConvertFrom-SecureString](ConvertFrom-SecureString.md) + Converts a secure string into an encrypted standard string. ### [ConvertTo-SecureString](ConvertTo-SecureString.md) + Converts encrypted standard strings to secure strings. ### [Get-Acl](Get-Acl.md) + Gets the security descriptor for a resource, such as a file or registry key. ### [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) + Gets information about the Authenticode signature in a file. ### [Get-Credential](Get-Credential.md) + Gets a credential object based on a user name and password. ### [Get-ExecutionPolicy](Get-ExecutionPolicy.md) + Gets the execution policies for the current session. ### [Get-PfxCertificate](Get-PfxCertificate.md) + Gets information about .pfx certificate files on the computer. ### [Set-Acl](Set-Acl.md) + Changes the security descriptor of a specified item, such as a file or a registry key. ### [Set-AuthenticodeSignature](Set-AuthenticodeSignature.md) + Adds an Authenticode signature to a Windows PowerShell script or other file. ### [Set-ExecutionPolicy](Set-ExecutionPolicy.md) + Changes the user preference for the Windows PowerShell execution policy. \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Security/Providers/Get-ChildItem-for-Certificate.md b/reference/3.0/Microsoft.PowerShell.Security/Providers/Get-ChildItem-for-Certificate.md index 07689f1b1e4a..92a488631ddc 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Providers/Get-ChildItem-for-Certificate.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Providers/Get-ChildItem-for-Certificate.md @@ -1,12 +1,12 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: Get-ChildItem for Certificate --- - # Get-ChildItem for Certificate + Gets certificate store locations, certificate stores, and certificates in the Windows PowerShell Cert: drive. ## Syntax @@ -17,6 +17,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI ``` ## Description + In the Cert: drive, the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet gets certificate store locations, certificate stores, and certificates. The Windows PowerShell [Certificate Provider](Certificate-Provider.md) adds the Cert: drive to Windows 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. @@ -30,6 +31,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI ## 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. @@ -47,6 +49,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI |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. @@ -60,6 +63,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI |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. @@ -73,6 +77,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI |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. @@ -90,6 +95,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI |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. @@ -105,6 +111,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI |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. @@ -122,9 +129,11 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI |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. ||| @@ -133,6 +142,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI |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. @@ -140,7 +150,7 @@ Get-ChildItem [-CodeSigningCert] [-DnsName ] [-EKU ] [-ExpiringI ## Example 1 ``` -C:\PS>PS cert:\> Get-ChildItem +PS> PS cert:\> Get-ChildItem Location : CurrentUser StoreNames : {TrustedPublisher, ClientAuthIssuer, Root, UserDS...} @@ -157,7 +167,7 @@ At the root of the Cert: drive, the Get-ChildItem cmdlet gets certificate store ## Example 2 ``` -C:\PS>PS cert:\LocalMachine\> Get-ChildItem +PS> PS cert:\LocalMachine\> Get-ChildItem Name : TrustedPublisher @@ -258,7 +268,7 @@ If the value of a property is an object name, use dot notation to display the ob ## Example 5 ``` -C:\PS>Get-ChildItem -Path cert: -CodeSigningCert -Recurse +PS> Get-ChildItem -Path cert: -CodeSigningCert -Recurse Description ----------- @@ -269,7 +279,7 @@ This command uses the CodeSigningCert and Recurse parameters of the Get-ChildIte ## Example 6 ``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\WebHosting -DNSName "*fabrikam*" +PS> Get-ChildItem -Path cert:\LocalMachine\WebHosting -DNSName "*fabrikam*" Description ----------- @@ -280,7 +290,7 @@ This command uses the DNSName parameter of the Get-ChildItem cmdlet to get all o ## Example 7 ``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\WebHosting -ExpiringInDays 30 +PS> Get-ChildItem -Path cert:\LocalMachine\WebHosting -ExpiringInDays 30 Description ----------- @@ -291,7 +301,7 @@ This command uses the ExpiringInDays parameter of the Get-ChildItem cmdlet to ge ## Example 8 ``` -C:\PS>Invoke-Command -ComputerName Srv01, Srv02 -ScriptBlock {Get-ChildItem -Path cert:\* -Recurse -ExpiringInDays 0} +PS> Invoke-Command -ComputerName Srv01, Srv02 -ScriptBlock {Get-ChildItem -Path cert:\* -Recurse -ExpiringInDays 0} Description ----------- @@ -302,7 +312,7 @@ This command uses the Invoke-Command cmdlet to run a Get-ChildItem command on th ## Example 9 ``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\My, cert:\LocalMachine\WebHosting -EKU "Server Authentication" +PS> Get-ChildItem -Path cert:\LocalMachine\My, cert:\LocalMachine\WebHosting -EKU "Server Authentication" Description ----------- @@ -313,7 +323,7 @@ This command uses the EKU parameter of the Get-ChildItem cmdlet to get all Serve ## Example 10 ``` -C:\PS>Get-ChildItem -Path cert:\* -Recurse -DNSName "*fabrikam*" -EKU "*Server*" | Where-Object {$_.SendAsTrustedIssuer -and $_.NotAfter -gt (get-date).AddDays.(30)} +PS> Get-ChildItem -Path cert:\* -Recurse -DNSName "*fabrikam*" -EKU "*Server*" | Where-Object {$_.SendAsTrustedIssuer -and $_.NotAfter -gt (get-date).AddDays.(30)} Description ----------- @@ -322,6 +332,7 @@ This command gets all certificates in the LocalMachine store location that have ``` ## See Also + [Certificate Provider](Certificate-Provider.md) [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) [Get-PfxCertificate](../Get-PfxCertificate.md) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Providers/Move-Item-for-Certificate.md b/reference/3.0/Microsoft.PowerShell.Security/Providers/Move-Item-for-Certificate.md index dd0e5b72f248..dc32cfdb066f 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Providers/Move-Item-for-Certificate.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Providers/Move-Item-for-Certificate.md @@ -1,12 +1,12 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: Move-Item for Certificate --- - # Move-Item for Certificate + Moves certificates from one certificate store to another certificate store. ## Syntax @@ -17,6 +17,7 @@ Move-Item [-Path] [[-Destination] ] [-Confirm] [-WhatIf] [ [[-Destination] ] [-Confirm] [-WhatIf] [ + 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. @@ -41,6 +43,7 @@ Move-Item [-Path] [[-Destination] ] [-Confirm] [-WhatIf] [ + Specifies the path to the original location of the certificate. Wildcards are permitted. ||| @@ -52,6 +55,7 @@ Move-Item [-Path] [[-Destination] ] [-Confirm] [-WhatIf] [ [[-Destination] ] [-Confirm] [-WhatIf] [ [[-Destination] ] [-Confirm] [-WhatIf] [ + 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. ||| @@ -85,12 +92,13 @@ Move-Item [-Path] [[-Destination] ] [-Confirm] [-WhatIf] [
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 +PS> Move-Item -Path cert:\LocalMachine\My\5DDC44652E62BF9AA1116DC41DE44AB47C87BDD0 -Destination cert:\LocalMachine\WebHosting Description ----------- @@ -103,7 +111,7 @@ Because the command uses absolute paths, you can run it from any Windows PowerSh ## Example 2 ``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine\My -EKU "Server Authentication" | Move-Item -Destination cert:\LocalMachine\WebHosting +PS> Get-ChildItem -Path cert:\LocalMachine\My -EKU "Server Authentication" | Move-Item -Destination cert:\LocalMachine\WebHosting Description ----------- @@ -114,6 +122,7 @@ It uses a pipeline operator to send the certificates to the Move-Item cmdlet, wh ``` ## See Also + [Certificate Provider](Certificate-Provider.md) [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Providers/New-Item-for-Certificate.md b/reference/3.0/Microsoft.PowerShell.Security/Providers/New-Item-for-Certificate.md index 0e850d0d59ce..6d3d66f00262 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Providers/New-Item-for-Certificate.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Providers/New-Item-for-Certificate.md @@ -1,12 +1,12 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: New-Item for Certificate --- - # New-Item for Certificate + Creates new certificate stores in the LocalMachine store location. ## Syntax @@ -19,6 +19,7 @@ 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 Windows PowerShell [Certificate Provider](Certificate-Provider.md) adds the Cert: drive to Windows 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. @@ -28,6 +29,7 @@ New-Item [-Path] [-Confirm] [-WhatIf] [] ## 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. ||| @@ -39,6 +41,7 @@ New-Item [-Path] [-Confirm] [-WhatIf] [] |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. ||| @@ -50,6 +53,7 @@ New-Item [-Path] [-Confirm] [-WhatIf] [] |Accept Wildcard Characters?|false| ### -Confirm + Prompts you for confirmation before executing the command. ||| @@ -61,6 +65,7 @@ New-Item [-Path] [-Confirm] [-WhatIf] [] |Accept Wildcard Characters?|false| ### -WhatIf + Describes what would happen if you executed the command without actually executing the command. ||| @@ -72,9 +77,11 @@ New-Item [-Path] [-Confirm] [-WhatIf] [] |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. ||| @@ -83,6 +90,7 @@ New-Item [-Path] [-Confirm] [-WhatIf] [] |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. @@ -90,7 +98,7 @@ New-Item [-Path] [-Confirm] [-WhatIf] [] ## Example 1 ``` -C:\PS>New-Item -Path Cert:\LocalMachine\TestStore +PS> New-Item -Path Cert:\LocalMachine\TestStore Name : TestStore @@ -105,7 +113,7 @@ The command returns a System.Security.Cryptography.X509Certificates.X509Store th ## Example 2 ``` -C:\PS>New-Item -Path Cert:\LocalMachine -Name TestStore +PS> New-Item -Path Cert:\LocalMachine -Name TestStore Name : TestStore @@ -118,7 +126,7 @@ This command uses the New-Item cmdlet to create the "TestStore" certificate stor ## Example 3 ``` -C:\PS>Invoke-Command -ComputerName Server01 { New-Item -Path Cert:\LocalMachine\TestStore } +PS> Invoke-Command -ComputerName Server01 { New-Item -Path Cert:\LocalMachine\TestStore } Description ----------- @@ -127,6 +135,7 @@ This command creates the TestStore certificate store on the Server01 remote comp ``` ## See Also + [Certificate Provider](Certificate-Provider.md) [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Providers/Remove-Item-for-Certificate.md b/reference/3.0/Microsoft.PowerShell.Security/Providers/Remove-Item-for-Certificate.md index 1e97acc9f0e0..ffa9002346d7 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Providers/Remove-Item-for-Certificate.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Providers/Remove-Item-for-Certificate.md @@ -1,12 +1,12 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: Remove-Item for Certificate --- - # Remove-Item for Certificate + Deletes certificate stores, certificates, and private keys. ## Syntax @@ -17,6 +17,7 @@ Remove-Item [-Path] [-DeleteKey] [-Confirm] [-WhatIf] [ [-DeleteKey] [-Confirm] [-WhatIf] [ [-DeleteKey] [-Confirm] [-WhatIf] [ + Specifies the path to the certificates and certificate stores that are being deleted. Wildcards are permitted. The parameter name ("-Path") is optional. ||| @@ -52,6 +55,7 @@ Remove-Item [-Path] [-DeleteKey] [-Confirm] [-WhatIf] [ [-DeleteKey] [-Confirm] [-WhatIf] [ [-DeleteKey] [-Confirm] [-WhatIf] [ + 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. ||| @@ -85,12 +92,13 @@ Remove-Item [-Path] [-DeleteKey] [-Confirm] [-WhatIf] [
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 +PS> Remove-Item -Path cert:\LocalMachine\CA\5DDC44652E62BF9AA1116DC41DE44AB47C87BDD0 Description ----------- @@ -101,7 +109,7 @@ This command deletes a certificate from the CA certificate store, but leaves the ## Example 2 ``` -C:\PS># Delete a certificate and private key on a remote computer +PS> # Delete a certificate and private key on a remote computer Description ----------- @@ -109,30 +117,30 @@ This series of commands enables delegation and then deletes the certificate and 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 +PS> 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 Windows PowerShell. -PS C:\> Connect-WSMan -ComputerName S1 -Credential Domain01\Admin01 +PS> 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 +PS> 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 +PS> $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 } +PS> 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 +PS> Get-ChildItem -Path cert:\LocalMachine\WebHosting -ExpiringInDays 0 | Remove-Item -DeleteKey Description ----------- @@ -145,7 +153,7 @@ It uses a pipeline operator to pass the certificates to the Remove-Item cmdlet, ## Example 4 ``` -C:\PS>Get-ChildItem -Path cert:\LocalMachine -DnsName *Fabrikam* | Remove-Item +PS> Get-ChildItem -Path cert:\LocalMachine -DnsName *Fabrikam* | Remove-Item Description ----------- @@ -154,6 +162,7 @@ This command deletes all certificates that have a DNS name that contains "Fabrik ``` ## See Also + [Certificate Provider](Certificate-Provider.md) [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Providers/certificate-provider.md b/reference/3.0/Microsoft.PowerShell.Security/Providers/certificate-provider.md index 6782b2927caf..ae38f58e360c 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Providers/certificate-provider.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Providers/certificate-provider.md @@ -1,22 +1,26 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: Certificate Provider --- - # Certificate Provider + ## PROVIDER NAME + Certificate ## DRIVES + Cert: ## SHORT DESCRIPTION + Provides access to X.509 certificate stores and certificates in Windows PowerShell. ## DETAILED DESCRIPTION + The Windows 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](../../Microsoft.PowerShell.Management/Set-Location.md) Cert:" command. @@ -50,6 +54,7 @@ title: Certificate Provider In addition, Windows 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](../../Microsoft.PowerShell.Core/Get-Command.md) -module *security". ## CAPABILITIES + ShouldProcess ## EXAMPLES @@ -57,18 +62,20 @@ title: Certificate Provider ### Navigating the Cert: Drive #### Example 1 + This command uses the Set-Location cmdlet to change the current location to the Cert: drive. -``` -set-location cert: +```powershell +Set-Location cert: ``` #### Example 2 + 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. -``` -set-location -path LocalMachine\Root +```powershell +Set-Location -Path LocalMachine\Root ``` @@ -77,49 +84,54 @@ set-location -path LocalMachine\Root ### Displaying the Contents of the Cert: Drive #### Example 1 + This command uses the Get-ChildItem cmdlet to display the certificate stores in the CurrentUser certificate store location. -``` -get-childitem -path cert:\CurrentUser +```powershell +Get-ChildItem -Path cert:\CurrentUser ``` If you are in the Cert: drive, you can omit the drive name. #### Example 2 + This command uses the Get-ChildItem cmdlet to display the certificates in the My certificate store. -``` -get-childitem -path cert:\CurrentUser\My +```powershell +Get-ChildItem -Path cert:\CurrentUser\My ``` If you are in the Cert: drive, you can omit the drive name. #### Example 3 + This command uses the Get-Item cmdlet to get the "My" certificate store and the Property parameter of Format-List with a wildcard character (*) to display all of the properties of the store. -``` -get-item -path cert:\CurrentUser\My | format-list * +```powershell +Get-Item -Path cert:\CurrentUser\My | Format-List * ``` #### Example 4 + 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. -``` -get-childitem -path cert:\LocalMachine\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B | format-list -property * +```powershell +Get-ChildItem -Path cert:\LocalMachine\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B | Format-List -Property * ``` #### Example 5 + 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 ``` @@ -127,62 +139,69 @@ Get-ChildItem -Path cert:\LocalMachine -Recurse | Format-Table -Property DnsName ### Opening the Certificates MMC Snap-in #### Example 1 + This command opens the Certificates MMC snap-in to manage the specified certificate. -``` -invoke-item cert:\CurrentUser\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B +```powershell +Invoke-Item cert:\CurrentUser\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B ``` ### Getting Selected Certificates #### Example 1 + 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 + 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". -``` +```powershell Get-ChildItem -Path cert:\LocalMachine\WebHosting -DNSName "*fabrikam*" ``` #### Example 3 + 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 4 + 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 + 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 6 + 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. -``` -Get-ChildItem -Path cert:\* -Recurse -DNSName "*fabrikam*" -EKU "*Client Authentication*" | Where-Object {$_.SendAsTrustedIssuer -and $_.NotAfter -gt (get-date).AddDays.(30)} +```powershell +Get-ChildItem -Path cert:\* -Recurse -DNSName "*fabrikam*" -EKU "*Client Authentication*" | Where-Object {$_.SendAsTrustedIssuer -and $_.NotAfter -gt (Get-Date).AddDays.(30)} ``` @@ -191,21 +210,23 @@ Get-ChildItem -Path cert:\* -Recurse -DNSName "*fabrikam*" -EKU "*Client Authen ### Moving Certificates #### Example 1 + 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 ``` #### Example 2 + 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 ``` @@ -213,16 +234,18 @@ Get-ChildItem -Path cert:\LocalMachine\My -SSLServerAuthentication | Move-Item - ### Deleting Certificates and Private Keys #### Example 1 + 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 2 + 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. @@ -235,35 +258,37 @@ Remove-Item -Path cert:\LocalMachine\CA\5DDC44652E62BF9AA1116DC41DE44AB47C87BDD0 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:\> Enable-WSManCredSSP -Role Client -DelegateComputer S1 +```powershell +Enable-WSManCredSSP -Role Client -DelegateComputer S1 -PS C:\> Connect-WSMan -ComputerName S1 -Credential Domain01\Admin01 +Connect-WSMan -ComputerName S1 -Credential Domain01\Admin01 -PS C:\> Set-Item -Path WSMan:\S1\Service\Auth\CredSSP -Value $true +Set-Item -Path WSMan:\S1\Service\Auth\CredSSP -Value $true -PS C:\> $s = New-PSSession S1 -Authentication CredSSP -Credential Domain01\Admin01 +$s = New-PSSession S1 -Authentication CredSSP -Credential Domain01\Admin01 -PS C:\> Invoke-Command -Session $s { Remove-Item cert:\LocalMachine\My\D2D38EBA60CAA1C12055A2E1C83B15AD450110C2 -DeleteKey } +Invoke-Command -Session $s { Remove-Item cert:\LocalMachine\My\D2D38EBA60CAA1C12055A2E1C83B15AD450110C2 -DeleteKey } ``` #### Example 3 + 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 ``` #### Example 4 + 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 ``` @@ -271,11 +296,12 @@ Get-ChildItem -Path cert:\LocalMachine -DnsName *Fabrikam* | Remove-Item ### Creating Certificate Stores #### Example 1 + 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 ``` @@ -283,11 +309,12 @@ New-Item -Path cert:\LocalMachine\CustomStore The command returns a System.Security.Cryptography.X509Certificates.X509Store that represents the new certificate store. #### Example 2 + 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 } ``` @@ -297,13 +324,14 @@ Invoke-Command -ComputerName Server01 { New-Item -Path cert:\LocalMachine\Custom ### Deleting Certificate Stores #### Example 1 + This command uses the Remove-Item cmdlet to delete the Test1 certificate store. It uses the Recurse parameter to delete the certificates in the Test1 store. In the Cert: drive, the Remove-Item cmdlet deletes user-created certificate stores from the LocalMachine store location. You cannot use the Remove-Item cmdlet to delete Windows system certificate stores. In the Cert: drive, the Remove-Item cmdlet supports only the Path, WhatIf, and Confirm parameters. All other parameters are ignored. -``` +```powershell Remove-Item -Path cert:\LocalMachine\TestStore -Recurse ``` @@ -311,25 +339,29 @@ Remove-Item -Path cert:\LocalMachine\TestStore -Recurse If the certificate store contains certificates and you omit the Recurse parameter, Remove-Item prompts you for confirmation before deleting any items. #### Example 2 + 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} ``` #### Example 3 + This command deletes all certificate stores in the LocalMachine store location that have "Test" in their names. -``` -Remove-Item -path cert:\LocalMachine\*test* -Recurse +```powershell +Remove-Item -Path cert:\LocalMachine\*test* -Recurse ``` ## 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. ### CodeSigningCert + Gets only those certificates with code-signing authority. This parameter gets certificates that have "Code Signing" in their EnhancedKeyUsageList property value. @@ -345,6 +377,7 @@ Remove-Item -path cert:\LocalMachine\*test* -Recurse - [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. @@ -358,6 +391,7 @@ Remove-Item -path cert:\LocalMachine\*test* -Recurse - [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. @@ -371,6 +405,7 @@ Remove-Item -path cert:\LocalMachine\*test* -Recurse - [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. @@ -382,6 +417,7 @@ Remove-Item -path cert:\LocalMachine\*test* -Recurse - [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. @@ -395,6 +431,7 @@ Remove-Item -path cert:\LocalMachine\*test* -Recurse - [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. @@ -408,6 +445,7 @@ Remove-Item -path cert:\LocalMachine\*test* -Recurse - [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) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md b/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md index 729398337033..6b3d06768ad4 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113389 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-Acl --- - # Set-Acl + ## SYNOPSIS + Changes the security descriptor of a specified item, such as a file or a registry key. + ## SYNTAX ### ByPath (Default) + ``` Set-Acl [-Path] [-AclObject] [[-CentralAccessPolicy] ] [-ClearCentralAccessPolicy] [-Passthru] [-Filter ] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] @@ -21,12 +24,14 @@ Set-Acl [-Path] [-AclObject] [[-CentralAccessPolicy] [-AclObject] [-Passthru] [-Filter ] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [-UseTransaction] [] ``` ### ByLiteralPath + ``` Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] ] [-ClearCentralAccessPolicy] [-Passthru] [-Filter ] [-Include ] [-Exclude ] @@ -34,6 +39,7 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl -Path "C:\Dog.txt" -PS C:\> Set-Acl -Path "C:\Cat.txt" -AclObject $DogACL + +```powershell +$DogACL = Get-Acl -Path "C:\Dog.txt" +Set-Acl -Path "C:\Cat.txt" -AclObject $DogACL ``` These commands copy the values from the security descriptor of the Dog.txt file to the security descriptor of the Cat.txt file. @@ -61,8 +68,9 @@ The value of the **Path** parameter is the path to the Cat.txt file. The value of the **AclObject** parameter is the model ACL, in this case, the ACL of Dog.txt as saved in the $DogACL variable. ### Example 2: Use the pipeline operator to pass a descriptor -``` -PS C:\> Get-Acl -Path "C:\Dog.txt" | Set-Acl -Path "C:\Cat.txt" + +```powershell +Get-Acl -Path "C:\Dog.txt" | Set-Acl -Path "C:\Cat.txt" ``` This command is almost the same as the command in the previous example, except that it uses a pipeline operator to send the security descriptor from a Get-Aclcommand to a `Set-Acl` command. @@ -74,9 +82,10 @@ The second command uses `Set-Acl` to apply the security descriptor of Dog.txt to When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. ### Example 3: Apply a security descriptor to multiple files -``` -PS C:\> $NewAcl = Get-Acl File0.txt -PS C:\> Get-ChildItem -Path "C:\temp" -Recurse -Include "*.txt" -Force | Set-Acl -AclObject $NewAcl + +```powershell +$NewAcl = Get-Acl File0.txt +Get-ChildItem -Path "C:\temp" -Recurse -Include "*.txt" -Force | Set-Acl -AclObject $NewAcl ``` These commands apply the security descriptors in the File0.txt file to all text files in the C:\Temp directory and all of its subdirectories. @@ -99,6 +108,7 @@ After reviewing the result, you can run the command again without the **Whatif** ## PARAMETERS ### -AclObject + Specifies an ACL with the desired property values. `Set-Acl` changes the ACL of item specified by the **Path** or **InputObject** parameter to match the values in the specified security object. @@ -117,6 +127,7 @@ Accept wildcard characters: False ``` ### -Exclude + Omits the specified items. The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". @@ -135,6 +146,7 @@ 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. @@ -153,6 +165,7 @@ Accept wildcard characters: True ``` ### -Include + Changes only the specified items. The value of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as "*.txt". @@ -171,6 +184,7 @@ Accept wildcard characters: True ``` ### -Passthru + Returns an object that represents the security descriptor that was changed. By default, this cmdlet does not generate any output. @@ -187,6 +201,7 @@ Accept wildcard characters: False ``` ### -Path + Changes the security descriptor of the specified item. Enter the path to an item, such as a path to a file or registry key. Wildcards are permitted. @@ -206,11 +221,12 @@ Accept wildcard characters: True ``` ### -CentralAccessPolicy + Establishes or changes the central access policy of the item. Enter the CAP ID or friendly name of a central access policy on the computer. Beginning in Windows Server® 2012, administrators can use Active Directory and Group Policy to set central access policies for users and groups. -For more information, see [Dynamic Access Control: Scenario Overview](http://go.microsoft.com/fwlink/?LinkId=238408). +For more information, see [Dynamic Access Control: Scenario Overview](/windows-server/identity/solution-guides/dynamic-access-control--scenario-overview). This parameter is introduced in Windows PowerShell 3.0. @@ -227,10 +243,11 @@ Accept wildcard characters: False ``` ### -ClearCentralAccessPolicy + Removes the central access policy from the specified item. Beginning in Windows Server® 2012, administrators can use Active Directory and Group Policy to set central access policies for users and groups. -For more information, see [Dynamic Access Control: Scenario Overview](http://go.microsoft.com/fwlink/?LinkId=238408). +For more information, see [Dynamic Access Control: Scenario Overview](/windows-server/identity/solution-guides/dynamic-access-control--scenario-overview). This parameter is introduced in Windows PowerShell 3.0. @@ -247,6 +264,7 @@ Accept wildcard characters: False ``` ### -InputObject + Changes the security descriptor of the specified object. Enter a variable that contains the object or a command that gets the object. @@ -268,6 +286,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + Changes the security descriptor of the specified item. Unlike **Path**, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcards. @@ -289,6 +308,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -304,6 +324,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -320,6 +341,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 about_Transactions. @@ -337,16 +359,19 @@ 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). ## INPUTS ### System.Security.AccessControl.ObjectSecurity, System.Security.AccessControl.CommonSecurityDescriptor + You can pipe an ACL object or a security descriptor to `Set-Acl`. ## OUTPUTS ### System.Security.AccessControl.FileSecurity + By default, `Set-Acl` does not generate any output. However, if you use the **Passthru** parameter, it generates a security object. The type of the security object depends on the type of the item. diff --git a/reference/3.0/Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md b/reference/3.0/Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md index 76e88594ba05..9b3470abad4a 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113391 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-AuthenticodeSignature --- - # Set-AuthenticodeSignature + ## SYNOPSIS + Adds an Authenticode signature to a Windows PowerShell script or other file. + ## SYNTAX ### ByPath (Default) + ``` Set-AuthenticodeSignature [-Certificate] [-IncludeChain ] [-TimestampServer ] [-HashAlgorithm ] [-Force] [-FilePath] [-WhatIf] [-Confirm] @@ -21,6 +24,7 @@ Set-AuthenticodeSignature [-Certificate] [-IncludeChain [-IncludeChain ] [-TimestampServer ] [-HashAlgorithm ] [-Force] -LiteralPath [-WhatIf] [-Confirm] @@ -28,16 +32,19 @@ Set-AuthenticodeSignature [-Certificate] [-IncludeChain $cert=Get-ChildItem -Path cert:\CurrentUser\my -CodeSigningCert -PS C:\> Set-AuthenticodeSignature -FilePath PsTestInternet2.ps1 -certificate $cert + +```powershell +$cert=Get-ChildItem -Path cert:\CurrentUser\my -CodeSigningCert +Set-AuthenticodeSignature -FilePath PsTestInternet2.ps1 -Certificate $cert ``` These commands retrieve a code-signing certificate from the Windows PowerShell certificate provider and use it to sign a Windows PowerShell script. @@ -48,10 +55,12 @@ The command stores the result in the $cert variable. The second command uses the Set-AuthenticodeSignature cmdlet to sign the PSTestInternet2.ps1 script. It uses the FilePath parameter to specify the name of the script and the Certificate parameter to specify that the certificate is stored in the $cert variable. + ### Example 2 -``` -PS C:\> $cert = Get-PfxCertificate C:\Test\Mysign.pfx -PS C:\> Set-AuthenticodeSignature -Filepath ServerProps.ps1 -Cert $cert + +```powershell +$cert = Get-PfxCertificate C:\Test\Mysign.pfx +Set-AuthenticodeSignature -FilePath ServerProps.ps1 -Certificate $cert ``` These commands use the Get-PfxCertificate cmdlet to find a code signing certificate. @@ -63,9 +72,11 @@ The second command uses Set-AuthenticodeSignature to sign the script. The FilePath parameter of Set-AuthenticodeSignature specifies the path to the script file being signed and the Cert parameter passes the $cert variable containing the certificate to Set-AuthenticodeSignature. If the certificate file is password protected, Windows PowerShell prompts you for the password. + ### Example 3 -``` -PS C:\> Set-AuthenticodeSignature -filepath c:\scripts\Remodel.ps1 -certificate $cert -IncludeChain All -TimeStampServer "http://timestamp.fabrikam.com/scripts/timstamper.dll" + +```powershell +Set-AuthenticodeSignature -FilePath c:\scripts\Remodel.ps1 -Certificate $cert -IncludeChain All -TimestampServer "http://timestamp.fabrikam.com/scripts/timstamper.dll" ``` This command adds a digital signature that includes the root authority in the trust chain, and it is signed by a third-party timestamp server. @@ -74,9 +85,11 @@ The command uses the FilePath parameter to specify the script being signed and t It uses the IncludeChain parameter to include all of the signatures in the trust chain (including the root authority). It also uses the TimeStampServer parameter to add a timestamp to the signature. This prevents the script from failing when the certificate expires. + ## PARAMETERS ### -Certificate + Specifies the certificate that will be used to sign the script or file. Enter a variable that stores an object representing the certificate or an expression that gets the certificate. @@ -96,6 +109,7 @@ Accept wildcard characters: False ``` ### -FilePath + Specifies the path to a file that is being signed. ```yaml @@ -111,6 +125,7 @@ Accept wildcard characters: False ``` ### -Force + Allows the cmdlet to append a signature to a read-only file. Even using the Force parameter, the cmdlet cannot override security restrictions. @@ -127,6 +142,7 @@ Accept wildcard characters: False ``` ### -HashAlgorithm + Specifies the hashing algorithm that Windows uses to compute the digital signature for the file. For Windows PowerShell 3.0, the default is SHA256, which is the Windows default hashing algorithm. @@ -146,6 +162,7 @@ Accept wildcard characters: False ``` ### -IncludeChain + Determines which certificates in the certificate trust chain are included in the digital signature. "NotRoot" is the default. @@ -168,6 +185,7 @@ Accept wildcard characters: False ``` ### -TimestampServer + Uses the specified time stamp server to add a time stamp to the signature. Type the URL of the time stamp server as a string. @@ -187,6 +205,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies the path to a file that is being signed. Unlike **FilePath**, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcards. @@ -206,6 +225,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -221,6 +241,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -237,11 +258,15 @@ 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). + ## INPUTS ### System.String + You can pipe a string that contains the file path to Set-AuthenticodeSignature. + ## OUTPUTS ### System.Management.Automation.Signature diff --git a/reference/3.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md b/reference/3.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md index 48a3afe94828..8453d0c22aaf 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Set-ExecutionPolicy.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113394 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-ExecutionPolicy --- - # Set-ExecutionPolicy + ## SYNOPSIS + Changes the user preference for the Windows PowerShell execution policy. + ## SYNTAX ``` @@ -19,6 +21,7 @@ Set-ExecutionPolicy [-ExecutionPolicy] [[-Scope] Set-ExecutionPolicy RemoteSigned + +```powershell +Set-ExecutionPolicy RemoteSigned ``` This command sets the user preference for the shell execution policy to RemoteSigned. + ### Example 2 + ``` -PS C:\> Set-ExecutionPolicy Restricted +PS> Set-ExecutionPolicy Restricted Set-ExecutionPolicy : Windows PowerShell updated your local preference successfully, but the setting is overridden by the group policy applied to your system. Due to the override, your shell will retain its current effective execution policy of "AllSigned". Contact your group policy administrator for more information. At line:1 char:20 + Set-ExecutionPolicy <<<< restricted ``` This command attempts to set the execution policy for the shell to "Restricted." The "Restricted" setting is written to the registry, but because it conflicts with a Group Policy, it is not effective, even though it is more restrictive than the policy. + ### Example 3 -``` -PS C:\> Invoke-Command -ComputerName Server01 -ScriptBlock {Get-ExecutionPolicy} | Set-ExecutionPolicy -Force + +```powershell +Invoke-Command -ComputerName Server01 -ScriptBlock {Get-ExecutionPolicy} | Set-ExecutionPolicy -Force ``` This command gets the execution policy from a remote computer and applies that execution policy to the local computer. @@ -54,13 +63,15 @@ The command uses the Invoke-Command cmdlet to send the command to the remote com Because you can pipe an ExecutionPolicy (Microsoft.PowerShell.ExecutionPolicy) object to **Set-ExecutionPolicy**, the **Set-ExecutionPolicy** command does not need an **ExecutionPolicy** parameter. The command uses the **Force** parameter to suppress the user prompt. + ### Example 4 + ``` The first command uses the **Set-ExecutionPolicy** cmdlet to set an execution policy of **AllSigned** for the current user. It uses the **Force** parameter to suppress the user prompts. -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy AllSigned -Force +PS> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy AllSigned -Force The second command uses the **List** parameter of the Get-ExecutionPolicy cmdlet to get the execution policies set in each scope. The results show that the execution policy that is set for the current user differs from the execution policy set for all users of the computer. -PS C:\> Get-ExecutionPolicy -List +PS> Get-ExecutionPolicy -List Scope ExecutionPolicy ----- --------------- @@ -71,39 +82,45 @@ CurrentUser AllSigned LocalMachine RemoteSigned -PS C:\> Get-ExecutionPolicy +PS> Get-ExecutionPolicy AllSigned ``` This example shows how to set an execution policy for a particular scope. + ### Example 5 -``` -PS C:\> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined + +```powershell +Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Undefined ``` This command uses an execution policy value of **Undefined** to effectively remove the execution policy that is set for the current user scope. As a result, the execution policy that is set in Group Policy or in the LocalMachine (all users) scope is effective. If you set the execution policy in all scopes to **Undefined** and the Group Policy is not set, the default execution policy, **Restricted**, is effective for all users of the computer. + ### Example 6 -``` -PS C:\> Set-ExecutionPolicy -Scope Process -ExecutionPolicy AllSigned + +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy AllSigned ``` This command sets an execution policy of **AllSigned** for only the current Windows PowerShell session. This execution policy is saved in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), so it does not affect the value in the registry. The variable and its value are deleted when the current session is closed. + ### Example 7 + ``` The first command uses the **Set-ExecutionPolicy** cmdlet to change the execution policy to RemoteSigned. -PS C:\> Set-ExecutionPolicy RemoteSigned +PS> Set-ExecutionPolicy RemoteSigned The second command uses the Get-ExecutionPolicy cmdlet to get the effective execution policy in the session. The output shows that it is **RemoteSigned**. -PS C:\> Get-ExecutionPolicy +PS> Get-ExecutionPolicy RemoteSigned The third command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is **RemoteSigned**. The **RemoteSigned** policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. -PS C:\> .\Start-ActivityTracker.ps1 +PS> .\Start-ActivityTracker.ps1 .\Start-ActivityTracker.ps1 : File .\Start-ActivityTracker.ps1 cannot be loaded. The file .\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 @@ -114,20 +131,22 @@ At line:1 char:1 The fourth command uses the Unblock-File cmdlet to unblock the script so it can run in the session.Before running an **Unblock-File** command, read the script contents and verify that it is safe. -PS C:\> Unblock-File -Path Start-ActivityTracker.ps1 +PS> Unblock-File -Path Start-ActivityTracker.ps1 The fifth and sixth commands show the effect of the **Unblock-File** command. The **Unblock-File** command does not change the execution policy. However, it unblocks the script so it will run in Windows PowerShell. -PS C:\> Get-ExecutionPolicy +PS> Get-ExecutionPolicy RemoteSigned -PS C:\> Start-ActivityTracker.ps1 +PS> Start-ActivityTracker.ps1 Task 1: ``` This example shows the effect of the **RemoteSigned** execution policy, which prevents you from running unsigned scripts that were downloaded from the Internet. It also shows how to use the Unblock-File cmdlet to unblock scripts, so that you can run them without changing the execution policy. + ## PARAMETERS ### -ExecutionPolicy + Specifies the new execution policy. Valid values are: @@ -151,6 +170,7 @@ Accept wildcard characters: False ``` ### -Force + Suppresses all prompts. By default, **Set-ExecutionPolicy** displays a warning whenever you change the execution policy. @@ -167,6 +187,7 @@ Accept wildcard characters: False ``` ### -Scope + Specifies the scope of the execution policy. The default is LocalMachine. @@ -194,6 +215,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -209,6 +231,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -225,22 +248,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). + ## INPUTS ### Microsoft.PowerShell.ExecutionPolicy, System.String + You can pipe an execution policy object or a string that contains the name of an execution policy to **Set-ExecutionPolicy**. + ## OUTPUTS ### None + This cmdlet does not return any output. + ## NOTES -* When you use **Set-ExecutionPolicy** in any scope other than **Process**, the new user preference is saved in the registry and remains unchanged until you change it. When the value of the **Scope** parameter is **Process**, the user preference is stored in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and it is deleted when the session in which it is effective is closed. + +- When you use **Set-ExecutionPolicy** in any scope other than **Process**, the new user preference is saved in the registry and remains unchanged until you change it. When the value of the **Scope** parameter is **Process**, the user preference is stored in the **PSExecutionPolicyPreference** environment variable ($env:PSExecutionPolicyPreference), instead of the registry, and it is deleted when the session in which it is effective is closed. If the "**Turn on Script Execution**" Group Policy is enabled for the computer or user, the user preference is saved, but it is not effective, and Windows PowerShell displays a message explaining the conflict. You cannot use **Set-ExecutionPolicy** to override a Group Policy, even if the user preference is more restrictive than the policy. -* + + ## RELATED LINKS [Get-AuthenticodeSignature](Get-AuthenticodeSignature.md) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md index 4c757ba401ae..1fd18a784121 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,20 +7,24 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113280 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: Add-Member --- - # Add-Member + ## SYNOPSIS + Adds custom properties and methods to an instance of a Windows PowerShell object. + ## SYNTAX ### TypeNameSet (Default) -```powershell + +``` Add-Member -InputObject -TypeName [-PassThru] [] ``` ### MemberSet -```powershell + +``` Add-Member [-MemberType] [-Name] [[-Value] ] [[-SecondValue] ] -InputObject [-TypeName ] [-Force] [-PassThru] @@ -28,20 +32,23 @@ Add-Member [-MemberType] [-Name] ``` ### NotePropertySingleMemberSet -```powershell + +``` Add-Member [-NotePropertyName] [-NotePropertyValue] -InputObject [-TypeName ] [-Force] [-PassThru] [] ``` ### NotePropertyMultiMemberSet -```powershell + +``` Add-Member [-NotePropertyMembers] -InputObject [-TypeName ] [-Force] [-PassThru] [] ``` ## DESCRIPTION + The **Add-Member** cmdlet lets you add members (properties and methods) to an instance of a Windows PowerShell object. For example, you can add a NoteProperty member that contains a description of the object or a ScriptMethod member that runs a script to change the object. @@ -60,14 +67,16 @@ You can use the **NotePropertyName** and **NotePropertyValue** parameters to def Also, beginning in Windows PowerShell 3.0, the **PassThru** parameter, which generates an output object, is needed less frequently. **Add-Member** now adds the new members directly to the input object of more types. For more information, see the **PassThru** parameter description. + ## EXAMPLES ### Example 1 + ``` -PS C:\> $a = dir c:\ps-test\test.txt -PS C:\> $a | Add-Member -NotePropertyName Status -NotePropertyValue Done -PS C:\> $a | Add-Member Status Done -PS C:\> $a.Status +PS> $a = dir c:\ps-test\test.txt +PS> $a | Add-Member -NotePropertyName Status -NotePropertyValue Done +PS> $a | Add-Member Status Done +PS> $a.Status Done ``` @@ -82,11 +91,13 @@ These commands are equivalent and can be used interchangeably. The fourth command uses dot notation to get the value of the Status property of the object in $a. As the output shows, the value is "Done". + ### Example 2 + ``` -PS C:\> $a = dir c:\ps-test\test.txt -PS C:\> $a | Add-Member -MemberType AliasProperty -Name FileLength -Value Length -PS C:\> $a.FileLength +PS> $a = dir c:\ps-test\test.txt +PS> $a | Add-Member -MemberType AliasProperty -Name FileLength -Value Length +PS> $a.FileLength 2394 ``` @@ -98,11 +109,13 @@ The first command use the Get-ChildItem cmdlet (alias = "dir") to get the Test.t The second command adds the FileLength alias property. The third command uses dot notation to get the value of the new FileLength property. + ### Example 3 + ``` -PS C:\> $a = "A string" -PS C:\> $a = $a | Add-Member @{StringUse="Display"} -PassThru -PS C:\> $a.StringUse +PS> $a = "A string" +PS> $a = $a | Add-Member @{StringUse="Display"} -PassThru +PS> $a.StringUse Display ``` @@ -113,11 +126,13 @@ The last command in the example displays the new property. The command uses the **NotePropertyMembers** parameter, but omits the parameter name, which is optional. The value of the **NotePropertyMembers** parameter is a hash table. The key is the note property name, StringUse, and the value is the note property value, Display. + ### Example 4 + ``` -PS C:\> $a = "This is a string." -PS C:\> $a = Add-Member -InputObject $a -MemberType ScriptMethod -Name PadBoth -Value {$p = $this.PadLeft($this.Length + 1); $p.PadRight($p.Length + 1)} -PassThru -PS C:\> $a.Padboth() +PS> $a = "This is a string." +PS> $a = Add-Member -InputObject $a -MemberType ScriptMethod -Name PadBoth -Value {$p = $this.PadLeft($this.Length + 1); $p.PadRight($p.Length + 1)} -PassThru +PS> $a.Padboth() This is a string. ``` @@ -136,10 +151,12 @@ The command includes the **PassThru** parameter which directs **Add-Member** to By default, **Add-Member** adds members to PSObjects and does not generate any output. The third command uses dot notation to call the new PadBoth script method on the object in the $a variable. + ### Example 5 + ``` -PS C:\> $event = Get-EventLog -LogName System -Newest 1 -PS C:\> $event.TimeWritten | Get-Member +PS> $event = Get-EventLog -LogName System -Newest 1 +PS> $event.TimeWritten | Get-Member TypeName: System.DateTime Name MemberType Definition @@ -151,8 +168,8 @@ AddMilliseconds Method System.DateTime AddMilliseconds(double value AddMinutes Method System.DateTime AddMinutes(double value)... -PS C:\> Add-Member -InputObject $event -MemberType AliasProperty -Name When -Value TimeWritten -SecondValue System.String -PS C:\> $event.When | Get-Member +PS> Add-Member -InputObject $event -MemberType AliasProperty -Name When -Value TimeWritten -SecondValue System.String +PS> $event.When | Get-Member TypeName: System.String Name MemberType Definition ---- ---------- ---------- @@ -179,9 +196,11 @@ The **SecondValue** parameter indicates that the value that the When method retu The fourth command uses dot notation to call the new When method. The command pipes the method value to the **Get-Member** cmdlet to confirm that it has returned a string. + ### Example 6 + ``` -PS C:\> function Copy-Property ($From, $To) +PS> function Copy-Property ($From, $To) { foreach ($p in Get-Member -InputObject $From -MemberType Property) { @@ -203,12 +222,14 @@ The **Add-Member** command adds the property of the From object to the To object It uses the **Force** parameter add members with the same member name. The last command in the function gives the new property the same name as the original property. + ### Example 7 + ``` -PS C:\> $Asset = New-Object -TypeName PSObject -PS C:\> $d = [ordered]@{Name="Server30";System="Server Core";PSVersion="3.0"} -PS C:\> $Asset | Add-Member -NotePropertyMembers $d -TypeName Asset -PS C:\> $Asset | Get-Member +PS> $Asset = New-Object -TypeName PSObject +PS> $d = [ordered]@{Name="Server30";System="Server Core";PSVersion="3.0"} +PS> $Asset | Add-Member -NotePropertyMembers $d -TypeName Asset +PS> $Asset | Get-Member TypeName: Asset Name MemberType Definition @@ -235,9 +256,11 @@ It uses the **TypeName** property to assign a new name, Asset, to the PSObject. The fourth command sends the new Asset object in the $Asset variable to the Get-Member cmdlet. The output shows that the object has a type name of "Asset" and the note properties that we defined in the ordered dictionary. + ## PARAMETERS ### -Force + Adds a new member even the object has a custom member with the same name. You cannot use **the** Force parameter to replace a standard member of a type. @@ -254,6 +277,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the object to which the new member is added. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -270,12 +294,13 @@ Accept wildcard characters: False ``` ### -MemberType + Specifies the type of the member to add. This parameter is mandatory. The valid values for this parameter are: "NoteProperty,AliasProperty,ScriptProperty,CodeProperty,ScriptMethod,CodeMethod" **AliasProperty**, **CodeMethod**, **CodeProperty**, **Noteproperty**, **ScriptMethod**, and **ScriptProperty**. -For information about these values, see [PSMemberTypes Enumeration](https://msdn.microsoft.com/library/system.management.automation.psmembertypes) in the MSDN library. +For information about these values, see [PSMemberTypes Enumeration](/dotnet/api/system.management.automation.psmembertypes) in the MSDN library. Not all objects have every type of member. If you specify a member type that the object does not have, Windows PowerShell returns an error. @@ -293,6 +318,7 @@ Accept wildcard characters: True ``` ### -Name + Specifies the name of the member to be added. ```yaml @@ -308,6 +334,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns the newly extended object. By default, this cmdlet does not generate any output. @@ -331,6 +358,7 @@ Accept wildcard characters: False ``` ### -SecondValue + Specifies optional additional information about **AliasProperty**, **ScriptProperty**, **CodeProperty**, or **CodeMethod** members. If used when adding an AliasProperty, this parameter must be a data type. A conversion (cast) to the specified data type is added to the value of the AliasProperty. @@ -353,6 +381,7 @@ Accept wildcard characters: False ``` ### -Value + Specifies the initial value of the added member. If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeMethod** member, you can supply optional, additional information by using the SecondValue parameter. @@ -369,6 +398,7 @@ Accept wildcard characters: False ``` ### -NotePropertyMembers + Specifies a hash table or ordered dictionary of note property names and values. Type a hash table or dictionary in which the keys are note property names and the values are note property values. @@ -389,6 +419,7 @@ Accept wildcard characters: False ``` ### -NotePropertyName + Adds a note property with the specified name. Use this parameter with the **NotePropertyValue** parameter. @@ -409,6 +440,7 @@ Accept wildcard characters: False ``` ### -NotePropertyValue + Adds a note property with the specified value. Use this parameter with the **NotePropertyName** parameter. @@ -429,6 +461,7 @@ Accept wildcard characters: False ``` ### -TypeName + Specifies a name for the type. When the type is a class in the System namespace or a type that has a type accelerator, you can enter the short name of the type. @@ -462,18 +495,25 @@ 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). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object type to Add-Member. + ## OUTPUTS ### None or System.Object + When you use the PassThru parameter, Add-Member returns the newly-extended object. Otherwise, this cmdlet does not generate any output. + ## NOTES -* You can add members only to PSObject objects. To determine whether an object is a PSObject object, use the "is" operator. For example, to test an object stored in the $obj variable, type "$obj -is \[PSObject\]". + +- You can add members only to PSObject objects. To determine whether an object is a PSObject object, use the "is" operator. For example, to test an object stored in the $obj variable, type "$obj -is \[PSObject\]". The names of the MemberType, Name, Value, and SecondValue parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: MemberType, Name, Value, SecondValue. @@ -483,7 +523,6 @@ If you include the parameter names, the parameters can appear in any order. The $this variable refers to the instance of the object to which the properties and methods are being added. For more information about the $this variable, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212). -* ## RELATED LINKS [Export-Clixml](Export-Clixml.md) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Add-Type.md b/reference/3.0/Microsoft.PowerShell.Utility/Add-Type.md index f84547d726e0..4b36ea4b2674 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Add-Type.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Add-Type.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135195 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: Add-Type --- - # Add-Type + ## SYNOPSIS + Adds a Microsoft .NET Framework type (a class) to a Windows PowerShell session. + ## SYNTAX ### FromSource (Default) + ``` Add-Type [-TypeDefinition] [-Language ] [-ReferencedAssemblies ] [-CodeDomProvider ] [-CompilerParameters ] [-OutputAssembly ] @@ -21,6 +24,7 @@ Add-Type [-TypeDefinition] [-Language ] [-ReferencedAssemblie ``` ### FromMember + ``` Add-Type [-Name] [-MemberDefinition] [-Namespace ] [-UsingNamespace ] [-Language ] [-ReferencedAssemblies ] [-CodeDomProvider ] @@ -29,6 +33,7 @@ Add-Type [-Name] [-MemberDefinition] [-Namespace ] [ ``` ### FromPath + ``` Add-Type [-Path] [-ReferencedAssemblies ] [-CompilerParameters ] [-OutputAssembly ] [-OutputType ] [-PassThru] [-IgnoreWarnings] @@ -36,6 +41,7 @@ Add-Type [-Path] [-ReferencedAssemblies ] [-CompilerParamet ``` ### FromLiteralPath + ``` Add-Type -LiteralPath [-ReferencedAssemblies ] [-CompilerParameters ] [-OutputAssembly ] [-OutputType ] [-PassThru] [-IgnoreWarnings] @@ -43,11 +49,13 @@ Add-Type -LiteralPath [-ReferencedAssemblies ] [-CompilerPa ``` ### FromAssemblyName + ``` Add-Type -AssemblyName [-PassThru] [-IgnoreWarnings] [] ``` ## DESCRIPTION + The **Add-Type** cmdlet lets you define a .NET Framework class in your Windows PowerShell session. You can then instantiate objects (by using the New-Object cmdlet) and use the objects, just as you would use any .NET Framework object. If you add an **Add-Type** command to your Windows PowerShell profile, the class is available in all Windows PowerShell sessions. @@ -58,11 +66,13 @@ You can use this feature to make Platform Invoke (P/Invoke) calls to unmanaged f If you specify source code, **Add-Type** compiles the specified source code and generates an in-memory assembly that contains the new .NET Framework types. You can use the parameters of **Add-Type** to specify an alternate language and compiler (CSharp is the default), compiler options, assembly dependencies, the class namespace, the names of the type, and the resulting assembly. + ## EXAMPLES ### Example 1 + ``` -PS C:\> $source = @" +PS> $source = @" public class BasicTest { public static int Add(int a, int b) @@ -75,10 +85,10 @@ public class BasicTest } } "@ -PS C:\> Add-Type -TypeDefinition $source -PS C:\> [BasicTest]::Add(4, 3) -PS C:\> $basicTestObject = New-Object BasicTest -PS C:\> $basicTestObject.Multiply(5, 2) +PS> Add-Type -TypeDefinition $source +PS> [BasicTest]::Add(4, 3) +PS> $basicTestObject = New-Object BasicTest +PS> $basicTestObject.Multiply(5, 2) ``` These commands add the BasicTest class to the session by specifying source code that is stored in a variable. @@ -98,12 +108,14 @@ The fourth command uses the **New-Object** cmdlet to instantiate an instance of It saves the new object in the $basicTestObject variable. The fifth command uses the Multiply method of $basicTestObject. + ### Example 2 + ``` -PS C:\> [BasicTest] | Get-Member -PS C:\> [BasicTest] | Get-Member -Static -PS C:\> $basicTestObject | Get-Member -PS C:\> [BasicTest] | Get-Member +PS> [BasicTest] | Get-Member +PS> [BasicTest] | Get-Member -Static +PS> $basicTestObject | Get-Member +PS> [BasicTest] | Get-Member TypeName: System.RuntimeType Name MemberType Definition @@ -112,7 +124,7 @@ Clone Method System.Object Clone() Equals Method System.Boolean Equals FindInterfaces Method System.Type[] FindInt ... -PS C:\> [BasicTest] | Get-Member -static +PS> [BasicTest] | Get-Member -static TypeName: BasicTest Name MemberType Definition @@ -121,7 +133,7 @@ Add Method static System.Int32 Add(Int32 a, Int32 b) Equals Method static System.Boolean Equals(Object objA, ReferenceEquals Method static System.Boolean ReferenceEquals(Obj -PS C:\> $basicTestObject | Get-Member +PS> $basicTestObject | Get-Member TypeName: BasicTest Name MemberType Definition @@ -145,9 +157,11 @@ The third command uses the **Get-Member** cmdlet to get the members of the objec This was the object instance that was created by using the **New-Object** cmdlet with the $BasicType class. The output reveals that the value of the $BasicTestObject variable is an instance of the BasicTest class and that it includes a member called Multiply. + ### Example 3 -``` -PS C:\> $accType = Add-Type -AssemblyName accessib* -PassThru + +```powershell +$accType = Add-Type -AssemblyName accessib* -PassThru ``` This command adds the classes from the Accessibility assembly to the current session. @@ -155,10 +169,12 @@ The command uses the **AssemblyName** parameter to specify the name of the assem The wildcard character allows you to get the correct assembly even when you are not sure of the name or its spelling. The command uses the **PassThru** parameter to generate objects that represent the classes that are added to the session, and it saves the objects in the $accType variable. + ### Example 4 + ``` -PS C:\> Add-Type -Path "c:\ps-test\Hello.vb" -PS C:\> [VBFromFile]::SayHello(", World") +PS> Add-Type -Path "c:\ps-test\Hello.vb" +PS> [VBFromFile]::SayHello(", World") # From Hello.vb @@ -179,9 +195,11 @@ The first command uses the **Add-Type** cmdlet to add the type defined in the He The command uses the **Path** parameter to specify the source file. The second command calls the SayHello function as a static method of the VBFromFile class. + ### Example 5 + ``` -PS C:\> $signature = @" +PS> $signature = @" [DllImport("user32.dll")] public static extern bool ShowWindowAsync(IntPtr hWnd, int nCmdShow); "@ @@ -200,7 +218,7 @@ The commands in this example demonstrate how to call native Windows APIs in Wind **Add-Type** uses the Platform Invoke (P/Invoke) mechanism to call a function in User32.dll from Windows PowerShell. The first command stores the C# signature of the **ShowWindowAsync** function in the $signature variable. -(For more information, see [ShowWindowAsync function](https://go.microsoft.com/fwlink/?LinkId=143643) in the MSDN library.) +(For more information, see [ShowWindowAsync function](https://msdn.microsoft.com/en-us/library/ms633549(VS.85).aspx) in the MSDN library.) To ensure that the resulting method will be visible in a Windows PowerShell session, the "public" keyword has been added to the standard signature. The second command uses the **Add-Type** cmdlet to add the ShowWindowAsync function to the Windows PowerShell session as a static method of a class that **Add-Type** creates. @@ -218,28 +236,32 @@ Then it uses the **MainWindowHandle** property of the current process and a valu To restore the window, the fourth command use a value of "4" for the window position, which represents the SW_RESTORE value. (SW_MAXIMIZE is 3.) + ### Example 6 -``` -PS C:\> Add-Type -MemberDefinition $jsMethod -Name "PrintInfo" -Language JScript + +```powershell +Add-Type -MemberDefinition $jsMethod -Name "PrintInfo" -Language JScript ``` This command uses the **Add-Type** cmdlet to add a method from inline JScript code to the Windows PowerShell session. It uses the **MemberDefinition** parameter to submit source code stored in the $jsMethod variable. It uses the **Name** parameter to specify a name for the class that **Add-Type** creates for the method and the **Language** parameter to specify the JScript language. + ### Example 7 + ``` -PS C:\> Add-Type -Path FSharp.Compiler.CodeDom.dll -PS C:\> Add-Type -Path FSharp.Compiler.CodeDom.dll -PS C:\> $Provider = New-Object Microsoft.FSharp.Compiler.CodeDom.FSharpCodeProvider -PS C:\> $fSharpCode = @" +PS> Add-Type -Path FSharp.Compiler.CodeDom.dll +PS> Add-Type -Path FSharp.Compiler.CodeDom.dll +PS> $Provider = New-Object Microsoft.FSharp.Compiler.CodeDom.FSharpCodeProvider +PS> $fSharpCode = @" let rec loop n = if n <= 0 then () else begin print_endline (string_of_int n); loop (n-1) end "@ -PS C:\> $fsharpType = Add-Type -TypeDefinition $fSharpCode -CodeDomProvider $Provider -PassThru | where { $_.IsPublic } -PS C:\> $fsharpType::loop(4) +PS> $fsharpType = Add-Type -TypeDefinition $fSharpCode -CodeDomProvider $Provider -PassThru | Where-Object { $_.IsPublic } +PS> $fsharpType::loop(4) 4 3 2 @@ -264,9 +286,11 @@ The **PassThru** parameter directs **Add-Type** to return a **Runtime** object t The **Where-Object** cmdlet is used because the FSharp provider generates non-public types to support the resulting public type. The fifth command calls the Loop method as a static method of the type stored in the $fSharpType variable. + ## PARAMETERS ### -AssemblyName + Specifies the name of an assembly that includes the types. **Add-Type** takes the types from the specified assembly. This parameter is required when you are creating types based on an assembly name. @@ -291,6 +315,7 @@ Accept wildcard characters: False ``` ### -CodeDomProvider + Specifies a code generator or compiler. **Add-Type** uses the specified compiler to compile the source code. The default is the CSharp compiler. @@ -310,6 +335,7 @@ Accept wildcard characters: False ``` ### -CompilerParameters + Specifies the options for the source code compiler. These options are sent to the compiler without revision. @@ -331,6 +357,7 @@ Accept wildcard characters: False ``` ### -IgnoreWarnings + Ignores compiler warnings. Use this parameter to prevent **Add-Type** from handling compiler warnings as errors. @@ -347,6 +374,7 @@ Accept wildcard characters: False ``` ### -Language + Specifies the language that is used in the source code. The **Add-Type** cmdlet uses the value of this parameter to select the appropriate CodeDomProvider. Valid values are "CSharp", "CSharpVersion3", "VisualBasic", and "JScript". @@ -365,6 +393,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies the path to source code files or assembly DLL files that contain the types. Unlike **Path**, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcards. @@ -384,6 +413,7 @@ Accept wildcard characters: False ``` ### -MemberDefinition + Specifies new properties or methods for the class. **Add-Type** generates the template code that is required to support the properties or methods. @@ -403,6 +433,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the class to create. This parameter is required when generating a type from a member definition. @@ -424,6 +455,7 @@ Accept wildcard characters: False ``` ### -Namespace + Specifies a namespace for the type. If this parameter is not included in the command, the type is created in the **Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes** namespace. @@ -442,6 +474,7 @@ Accept wildcard characters: False ``` ### -OutputAssembly + Generates a DLL file for the assembly with the specified name in the location. Enter a path (optional) and file name. Wildcard characters are permitted. @@ -460,9 +493,10 @@ Accept wildcard characters: False ``` ### -OutputType + Specifies the output type of the output assembly. Valid values are **Library**, **ConsoleApplication**, and **WindowsApplication**. -For more information about the values, see [OutputAssemblyType Enumeration](https://msdn.microsoft.com/library/microsoft.powershell.commands.outputassemblytype) in the MSDN library. +For more information about the values, see [OutputAssemblyType Enumeration](/dotnet/api/microsoft.powershell.commands) in the MSDN library. By default, no output type is specified. @@ -481,6 +515,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns a **System.Runtime** object that represents the types that were added. By default, this cmdlet does not generate any output. @@ -497,6 +532,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path to source code files or assembly DLL files that contain the types. If you submit source code files, **Add-Type** compiles the code in the files and creates an in-memory assembly of the types. @@ -518,6 +554,7 @@ Accept wildcard characters: False ``` ### -ReferencedAssemblies + Specifies the assemblies upon which the type depends. By default, **Add-Type** references System.dll and System.Management.Automation.dll. The assemblies that you specify by using this parameter are referenced in addition to the default assemblies. @@ -537,6 +574,7 @@ Accept wildcard characters: False ``` ### -TypeDefinition + Specifies the source code that contains the type definitions. Enter the source code in a string or here-string, or enter a variable that contains the source code. For more information about here-strings, see about_Quoting_Rules (http://go.microsoft.com/fwlink/?LinkID=113253). @@ -558,6 +596,7 @@ Accept wildcard characters: False ``` ### -UsingNamespace + Specifies other namespaces that are required for the class. This is much like the Using keyword in C#. @@ -578,18 +617,25 @@ 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). + ## INPUTS ### None + You cannot pipe objects to Add-Type. + ## OUTPUTS ### None or System.Type + When you use the **PassThru** parameter, **Add-Type** returns a **System.Type** object that represents the new type. Otherwise, this cmdlet does not generate any output. + ## NOTES -* The types that you add exist only in the current session. To use the types in all sessions, add them to your Windows PowerShell profile. For more information about the profile, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729). + +- The types that you add exist only in the current session. To use the types in all sessions, add them to your Windows PowerShell profile. For more information about the profile, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729). Type names (and namespaces) must be unique within a session. You cannot unload a type or change it. @@ -601,6 +647,7 @@ As a result, types written in these languages cannot be used with **Add-Type**. This cmdlet is based on the **CodeDomProvider** class. For more information about this class, see the Microsoft .NET Framework SDK. + ## RELATED LINKS [Add-Member](Add-Member.md) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Clear-Variable.md b/reference/3.0/Microsoft.PowerShell.Utility/Clear-Variable.md index 42fa93e7bd65..874574459ac8 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Clear-Variable.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Clear-Variable.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113285 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: Clear-Variable --- - # Clear-Variable + ## SYNOPSIS + Deletes the value of a variable. + ## SYNTAX ``` @@ -19,22 +21,27 @@ Clear-Variable [-Name] [-Include ] [-Exclude ] [- ``` ## DESCRIPTION + The Clear-Variable cmdlet deletes the data stored in a variable, but it does not delete the variable. As a result, the value of the variable is NULL (empty). If the variable has a specified data or object type, Clear-Variable preserves the type of the object stored in the variable. + ## EXAMPLES ### Example 1 -``` -PS C:\> Clear-Variable my* -Scope Global + +```powershell +Clear-Variable my* -Scope Global ``` This command deletes the value of global variables that have names that begin with "my". + ### Example 2 + ``` -PS C:\> $a=3 -PS C:\> &{ Clear-Variable a } -PS C:\> $a +PS> $a=3 +PS> &{ Clear-Variable a } +PS> $a 3 ``` @@ -43,16 +50,20 @@ The first command sets the value of the variable $a to "3". The second command uses the invoke operator (&) to run a Clear-Variable command in a new scope. The variable is cleared in the child scope (although it did not exist), but it is not cleared in the local scope. The third command, which gets the value of $a, shows that the value "3" is unaffected. + ### Example 3 -``` -PS C:\> Clear-variable -Name Processes + +```powershell +Clear-Variable -Name Processes ``` This command deletes the value of the $processes variable. The $processes variable still exists, but the value is null. + ## PARAMETERS ### -Exclude + Omits the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". @@ -71,6 +82,7 @@ Accept wildcard characters: True ``` ### -Force + Allows the cmdlet to clear a variable even if it is read-only. Even using the Force parameter, the cmdlet cannot clear constants. @@ -87,6 +99,7 @@ Accept wildcard characters: False ``` ### -Include + Clears only the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". @@ -105,6 +118,7 @@ Accept wildcard characters: True ``` ### -Name + Specifies the name of the variable to be cleared. Wildcards are permitted. This parameter is required, but the parameter name ("Name") is optional. @@ -122,6 +136,7 @@ Accept wildcard characters: True ``` ### -PassThru + Returns an object representing the cleared variable. By default, this cmdlet does not generate any output. @@ -138,6 +153,7 @@ Accept wildcard characters: False ``` ### -Scope + Specifies the scope in which this alias is valid. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. @@ -156,6 +172,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -171,6 +188,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -187,18 +205,25 @@ 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). + ## INPUTS ### None + You cannot pipe objects to Clear-Variable. + ## OUTPUTS ### None or System.Management.Automation.PSVariable + When you use the PassThru parameter, Clear-Variable generates a System.Management.Automation.PSVariable object representing the cleared variable. Otherwise, this cmdlet does not generate any output. + ## NOTES -* To delete a variable, along with its value, use Remove-Variable or Remove-Item. + +- To delete a variable, along with its value, use Remove-Variable or Remove-Item. Clear-Variable will not delete the values of variables that are set as constants or owned by the system, even if you use the -Force parameter. @@ -208,7 +233,6 @@ It does not create a variable with a null value. You can also refer to Clear-Variable by its built-in alias, "clv". For more information, see about_Aliases. -* ## RELATED LINKS [Get-Variable](Get-Variable.md) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Compare-Object.md b/reference/3.0/Microsoft.PowerShell.Utility/Compare-Object.md index 64624d6c0a11..cdcf7265e0c6 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Compare-Object.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Compare-Object.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113286 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: Compare-Object --- - # Compare-Object + ## SYNOPSIS + Compares two sets of objects. + ## SYNTAX ``` @@ -20,34 +22,41 @@ Compare-Object [-ReferenceObject] [-DifferenceObject] ``` ## DESCRIPTION + The Compare-Object cmdlet compares two sets of objects. One set of objects is the "reference set," and the other set is the "difference set." The result of the comparison indicates whether a property value appeared only in the object from the reference set (indicated by the \<= symbol), only in the object from the difference set (indicated by the =\> symbol) or, if the **IncludeEqual** parameter is specified, in both objects (indicated by the == symbol). NOTE: If the reference set or the difference set is null ($null), Compare-Object generates a terminating error. + ## EXAMPLES ### Example 1 -``` -PS C:\> compare-object -referenceobject $(get-content C:\test\testfile1.txt) -differenceobject $(get-content C:\test\testfile2.txt) + +```powershell +Compare-Object -ReferenceObject $(Get-Content C:\test\testfile1.txt) -DifferenceObject $(Get-Content C:\test\testfile2.txt) ``` This command compares the contents of two text files. It displays only the lines that appear in one file or in the other file, not lines that appear in both files. + ### Example 2 -``` -PS C:\> compare-object -referenceobject $(get-content C:\Test\testfile1.txt) -differenceobject $(get-content C:\Test\testfile2.txt) -includeequal + +```powershell +Compare-Object -ReferenceObject $(Get-Content C:\Test\testfile1.txt) -DifferenceObject $(Get-Content C:\Test\testfile2.txt) -includeequal ``` This command compares each line of content in two text files. It displays all lines of content from both files, indicating whether each line appears in only Textfile1.txt or Textfile2.txt or whether each line appears in both files. + ### Example 3 + ``` -PS C:\> $processes_before = get-process -PS C:\> notepad -PS C:\> $processes_after = get-process -PS C:\> compare-object -referenceobject $processes_before -differenceobject $processes_after +PS> $processes_before = get-process +PS> notepad +PS> $processes_after = get-process +PS> compare-object -referenceobject $processes_before -differenceobject $processes_after ``` These commands compare two sets of process objects. @@ -61,9 +70,11 @@ The third command uses the Get-Process cmdlet again and stores the resulting pro The fourth command uses the Compare-Object cmdlet to compare the two sets of process objects. It displaysthe differences between them, which include the new instance of Notepad. + ## PARAMETERS ### -CaseSensitive + Indicates that comparisons should be case-sensitive. ```yaml @@ -79,6 +90,7 @@ Accept wildcard characters: False ``` ### -Culture + Specifies the culture to use for comparisons. ```yaml @@ -94,6 +106,7 @@ Accept wildcard characters: False ``` ### -DifferenceObject + Specifies the objects that are compared to the reference objects. ```yaml @@ -109,6 +122,7 @@ Accept wildcard characters: False ``` ### -ExcludeDifferent + Displays only the characteristics of compared objects that are equal. ```yaml @@ -124,6 +138,7 @@ Accept wildcard characters: False ``` ### -IncludeEqual + Displays characteristics of compared objects that are equal. By default, only characteristics that differ between the reference and difference objects are displayed. @@ -140,6 +155,7 @@ Accept wildcard characters: False ``` ### -PassThru + Passes the objects that differed to the pipeline. By default, this cmdlet does not generate any output. @@ -156,6 +172,7 @@ Accept wildcard characters: False ``` ### -Property + Specifies the properties of the reference and difference objects to compare. ```yaml @@ -171,6 +188,7 @@ Accept wildcard characters: False ``` ### -ReferenceObject + Objects used as a reference for comparison. ```yaml @@ -186,6 +204,7 @@ Accept wildcard characters: False ``` ### -SyncWindow + Specifies the number of adjacent objects that Compare-Object inspects while looking for an match in a collection of objects. Compare-Object examines adjacent objects when it doesn't find the object in the same position in a collection. The default value is \[Int32\]::MaxValue, which means that Compare-Object examines the entire object collection. @@ -203,16 +222,22 @@ 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). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe a DifferenceObject object to Compare-Object. + ## OUTPUTS ### None, or the objects that are different + When you use the PassThru parameter, Compare-Object returns the objects that differed. Otherwise, this cmdlet does not generate any output. + ## NOTES ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md index 7fdbbbc1a620..100d657e8bc4 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,25 +7,30 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135201 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertFrom-Csv --- - # ConvertFrom-Csv + ## SYNOPSIS + Converts object properties in comma-separated value (CSV) format into CSV versions of the original objects. + ## SYNTAX ### Delimiter (Default) -```powershell + +``` ConvertFrom-Csv [-InputObject] [[-Delimiter] ] [-Header ] [] ``` ### UseCulture -```powershell + +``` ConvertFrom-Csv [-InputObject] -UseCulture [-Header ] [] ``` ## DESCRIPTION + The ConvertFrom-CSV cmdlet creates objects from CSV variable-length strings that are generated by the ConvertTo-CSV cmdlet. You can use the parameters of the ConvertFrom-CSV cmdlet to specify the column header row, which determines the property names of the resulting objects, to specify the item delimiter, or to direct ConvertFrom-CSV to use the list separator for the current culture as the delimiter. @@ -36,12 +41,14 @@ The CSV versions of the objects do not have any methods. You can also use the Export-CSV and Import-CSV cmdlets to convert objects to CSV strings in a file (and back). These cmdlets are the same as the ConvertTo-CSV and ConvertFrom-CSV cmdlets, except that they save the CSV strings in a file. + ## EXAMPLES ### Example 1 -``` -PS C:\> $p = get-process | convertto-csv -PS C:\> $p | convertfrom-csv + +```powershell +$p = Get-Process | ConvertTo-Csv +$p | ConvertFrom-Csv ``` These commands convert the processes on the local computer into CSV format and then restore them to object form. @@ -52,10 +59,12 @@ The CSV strings are saved in the $p variable. The second command uses a pipeline operator to send the CSV strings in the $p variable to the ConvertFrom-CSV cmdlet. The cmdlet converts the CSV strings into CSV versions of the original process objects. + ### Example 2 -``` -PS C:\> $date = get-date | convertto-csv -delimiter ";" -PS C:\> convertfrom-csv -inputobject $date -delimiter ";" + +```powershell +$date = Get-Date | ConvertTo-Csv -Delimiter ";" +ConvertFrom-Csv -InputObject $date -Delimiter ";" ``` These commands convert a data object to CSV format and then to CSV object format. @@ -67,12 +76,14 @@ The strings are saved in the $date variable. The second command uses the ConvertFrom-CSV cmdlet to convert the CSV strings in the $date variable back to object format. The command uses the InputObject parameter to specify the CSV strings and the Delimiter parameter to specify the semicolon delimiter. + ### Example 3 + ``` -PS C:\> $j = start-job -scriptblock { get-process } | convertto-csv -PS C:\> $header = "MoreData","StatusMessage","Location","Command","State","Finished","InstanceId","SessionId","Name","ChildJobs","Output","Error","Progress","Verbose","Debug","Warning","StateChanged" +PS> $j = start-job -scriptblock { get-process } | convertto-csv +PS> $header = "MoreData","StatusMessage","Location","Command","State","Finished","InstanceId","SessionId","Name","ChildJobs","Output","Error","Progress","Verbose","Debug","Warning","StateChanged" # Delete header from $j -PS C:\> $j = $j[0], $j[2..($j.count - 1)] +PS> $j = $j[0], $j[2..($j.count - 1)] $j | convertfrom-csv -header $header MoreData : True @@ -108,10 +119,12 @@ The third command deletes the original header (the second line) from the CSV str The fourth command uses the ConvertFrom-CSV cmdlet to convert the CSV strings to a CSV version of the job object. The command uses a pipeline operator to send the content in $j to ConvertFrom-CSV. The resulting object has "MoreData" and "State" properties, as specified by the header. + ### Example 4 -``` -PS C:\> (get-culture).textinfo.listseparator -PS C:\> ConvertFrom-Csv -inputobject $services -UseCulture + +```powershell +(Get-Culture).textinfo.listseparator +ConvertFrom-Csv -InputObject $services -UseCulture ``` The command uses the ConvertFrom-CSV cmdlet to convert CSV strings of service objects that had been converted by the ConvertTo-CSV cmdlet. @@ -121,9 +134,11 @@ When using the UseCulture parameter, be sure that the list separator of the curr Otherwise, ConvertFrom-CSV cannot generate objects from the CSV strings. In this example, a Get-Culture command was used to verify the list separator, before the ConvertFrom-CSV command was used. + ## PARAMETERS ### -Delimiter + Specifies the delimiter that separates the property values in the CSV strings. The default is a comma (,). Enter a character, such as a colon (:). @@ -145,6 +160,7 @@ Accept wildcard characters: False ``` ### -Header + Specifies an alternate column header row for the imported string. The column header determines the names of the properties of the object that ConvertFrom-CSV creates. @@ -170,6 +186,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the CSV strings to be converted to objects. Enter a variable that contains the CSV strings or type a command or expression that gets the CSV strings. You can also pipe the CSV strings to ConvertFrom-CSV. @@ -187,6 +204,7 @@ Accept wildcard characters: False ``` ### -UseCulture + Use the list separator for the current culture as the string delimiter. The default is a comma (,). @@ -207,23 +225,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). + ## INPUTS ### System.String + You can pipe CSV strings to ConvertFrom-CSV. + ## OUTPUTS ### System.Management.Automation.PSObject + ConvertFrom-CSV returns the objects described by the properties in the CSV strings. + ## NOTES -* Because the imported objects are CSV versions of the object type, they are not recognized and formatted by the Windows PowerShell type formatting entries that format the non-CSV versions of the object type. + +- Because the imported objects are CSV versions of the object type, they are not recognized and formatted by the Windows PowerShell type formatting entries that format the non-CSV versions of the object type. In CSV format, each object is represented by a comma-separated list of the property values of the object. The property values are converted to strings (by using the ToString() method of the object), so they are generally represented by the name of the property value. ConvertTo-Csv does not export the methods of the object. -* ## RELATED LINKS [ConvertTo-Csv](ConvertTo-Csv.md) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md index 5a756463ab7f..7f92d8a01753 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Json.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -33,7 +33,7 @@ This cmdlet is introduced in PowerShell 3.0. ### Example 1 ``` -PS C:\> Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json +PS> Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json DisplayHint : 2 @@ -141,7 +141,7 @@ You can pipe a JSON string to **ConvertFrom-Json**. ## RELATED LINKS -[An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET](http://msdn.microsoft.com/library/bb299886.aspx) +[An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET](https://msdn.microsoft.com/library/bb299886.aspx) [ConvertTo-Json](ConvertTo-Json.md) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index 260216773be8..30777e86e2c4 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113288 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertFrom-StringData --- - # ConvertFrom-StringData + ## SYNOPSIS + Converts a string containing one or more key/value pairs to a hash table. + ## SYNTAX ``` @@ -18,6 +20,7 @@ ConvertFrom-StringData [-StringData] [] ``` ## DESCRIPTION + The ConvertFrom-StringData cmdlet converts a string that contains one or more key/value pairs into a hash table. Because each key/value pair must be on a separate line, here-strings are often used as the input format. @@ -34,13 +37,14 @@ Unescaped backslash characters, such as those that are commonly used in file pat ## EXAMPLES ### Example 1 + ``` -PS C:\> $here = @' +PS> $here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. Msg3 = The specified variable does not exist. '@ -PS C:\> convertfrom-stringdata -stringdata $here +PS> convertfrom-stringdata -stringdata $here Name Value ---- ----- @@ -55,20 +59,22 @@ In a single-quoted string, values are not substituted for variables and expressi The first command creates a here-string and saves it in the $here variable. The second command uses the ConvertFrom-StringData cmdlet to convert the here-string in the $here variable to a hash table. + ### Example 2 + ``` -PS C:\> $p = @" +PS> $p = @" ISE = Windows PowerShell Integrated Scripting Environment "@ -PS C:\> $p | get-member +PS> $p | get-member TypeName: System.String Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() -PS C:\> $hash = convertfrom-stringdata -stringdata $p -PS C:\> $hash | get-member +PS> $hash = convertfrom-stringdata -stringdata $p +PS> $hash | get-member TypeName: System.Collections.Hashtable Name MemberType Definition @@ -89,9 +95,11 @@ The command stores the result in the $hash variable. The final command uses a pipeline operator (|) to send the $hash variable to the Get-Member cmdlet. The result shows that the content of the $hash variable is a hash table (System.Collections.Hashtable). + ### Example 3 + ``` -PS C:\> convertfrom-stringdata -stringdata @' +PS> convertfrom-stringdata -stringdata @' Name = Disks.ps1 # Category is optional. @@ -114,12 +122,14 @@ Either format is valid. The here-string includes a comment about one of the strings. Comments are valid in strings, provided that the comment is on a different line than a key/value pair. + ### Example 4 + ``` -PS C:\> $a = convertfrom-stringdata -stringdata "Top = Red `n Bottom = Blue" -PS C:\> "Top = " + $a.Top +PS> $a = convertfrom-stringdata -stringdata "Top = Red `n Bottom = Blue" +PS> "Top = " + $a.Top Top = Red -PS C:\> "Bottom = " + $a.Bottom +PS> "Bottom = " + $a.Bottom Bottom = Blue ``` @@ -129,17 +139,19 @@ To satisfy the condition that each key/value pair must be on a separate line, it The result is a hash table of the input. The remaining commands display the output. + ### Example 5 + ``` -PS C:\> $TextMsgs = DATA { +PS> $TextMsgs = DATA { ConvertFrom-StringData @' Text001 = The $Notebook variable contains the name of the user's system notebook. Text002 = The $MyNotebook variable contains the name of the user's private notebook. '@ } -PS C:\> $TextMsgs.Text001 +PS> $TextMsgs.Text001 The $Notebook variable contains the name of the user's system notebook. -PS C:\> $TextMsgs.Text002 +PS> $TextMsgs.Text002 The $MyNotebook variable contains the name of the user's private notebook. ``` @@ -148,15 +160,17 @@ The statements below the DATA section display the text to the user. Because the text includes variable names, it must be enclosed in a single-quoted string so that the variables are interpreted literally and not expanded. Variables are not permitted in the DATA section. + ### Example 6 + ``` -PS C:\> $here = @' +PS> $here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. Msg3 = The specified variable does not exist. '@ -PS C:\> $hash = $here | convertfrom-stringdata -PS C:\> $hash +PS> $hash = $here | convertfrom-stringdata +PS> $hash Name Value ---- ----- @@ -172,9 +186,11 @@ The second command uses a pipeline operator (|) to send the $here variable to Co The command saves the result in the $hash variable. The final command displays the contents of the $hash variable. + ### Example 7 + ``` -PS C:\> ConvertFrom-StringData @" +PS> ConvertFrom-StringData @" Vincentio = Heaven doth with us as we with torches do,\nNot light them for themselves; for if our virtues\nDid not go forth of us, 'twere all alike\nAs if we had them not. Angelo = Let there be some more test made of my metal,\nBefore so noble and so great a figure\nBe stamp'd upon it. "@ | Format-List @@ -194,9 +210,11 @@ Value : Heaven doth with us as we with torches do, This example shows the use of escape characters to create new lines and return characters in ConvertFrom-StringData. In this example, the escape sequence **\n** is used to create new lines within a block of text (the value, in the resulting hash table) that is associated with a name or item (the name, in the resulting hash table). + ### Example 8 + ``` -PS C:\> ConvertFrom-StringData "Message=Look in c:\\Windows\\System32" +PS> ConvertFrom-StringData "Message=Look in c:\\Windows\\System32" Name Value ---- ----- Message Look in c:\Windows\System32 @@ -204,9 +222,11 @@ Message Look in c:\Windows\System32 This example shows how to use of the backslash escape character in the string data to allow a file path to render correctly in the resulting ConvertFrom-StringData hash table. The double backslash ensures that the literal backslash characters render correctly in the hash table output. + ## PARAMETERS ### -StringData + Specifies the string to be converted. You can use this parameter or pipe a string to ConvertFrom-StringData. The parameter name is optional. @@ -233,17 +253,24 @@ 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). + ## INPUTS ### System.String + You can pipe a string containing a key/value pair to ConvertFrom-StringData. + ## OUTPUTS ### System.Collections.Hashtable + ConvertFrom-StringData returns a hash table that it creates from the key/value pairs. + ## NOTES -* A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules. + +- A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules. ConvertFrom-StringData can be useful in scripts that display user messages in multiple spoken languages. You can use the dictionary-style hash tables to isolate text strings from code, such as in resource files, and to format the text strings for use in translation tools. diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Csv.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Csv.md index 7176e6474107..98bfa67ffeb5 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Csv.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Csv.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,23 +7,28 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135203 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertTo-Csv --- - # ConvertTo-Csv + ## SYNOPSIS + Converts objects into a series of comma-separated value (CSV) variable-length strings. + ## SYNTAX ### Delimiter (Default) + ``` ConvertTo-Csv [-InputObject] [[-Delimiter] ] [-NoTypeInformation] [] ``` ### UseCulture + ``` ConvertTo-Csv [-InputObject] [-UseCulture] [-NoTypeInformation] [] ``` ## DESCRIPTION + The `ConvertTo-CSV` cmdlet returns a series of comma-separated (CSV) strings that represents the objects that you submit. You can then use the `ConvertFrom-Csv` cmdlet to re-create objects from the CSV strings. The resulting objects are CSV versions of the original objects that consist of string representations of the property values and no methods. @@ -36,6 +41,7 @@ You can use the parameters of the `ConvertTo-CSV` cmdlet to specify a delimiter ## EXAMPLES ### Example 1: Convert an object to CSV + ```powershell Get-Process powershell | ConvertTo-Csv <# @@ -53,6 +59,7 @@ The command uses the `Get-Process` cmdlet to get the PowerShell process on the l It uses a pipeline operator (`|`) to send the command to the `ConvertTo-CSV` cmdlet, which converts it to a series of comma-separated strings. ### Example 2: Convert a DateTime object to CSV + ```powershell $Date = Get-Date ConvertTo-Csv -InputObject $Date -Delimiter ";" -NoTypeInformation @@ -69,8 +76,9 @@ It uses the `-Delimiter` parameter to specify the delimiter that separates the o It uses the `-NoTypeInformation` parameter to suppress the `#TYPE` string. ### Example 3: Convert the PowerShell event log to CSV + ```powershell -Get-EventLog -Log "windows powershell" | ConvertTo-Csv -UseCulture +Get-EventLog -LogName "windows powershell" | ConvertTo-Csv -UseCulture ``` This command converts the Windows PowerShell event log on the local computer to a series of CSV strings. @@ -82,6 +90,7 @@ The command uses the `-UseCulture` parameter, which uses the list separator for ## PARAMETERS ### -Delimiter + Specifies a delimiter to separate the property values. The default is a comma (`,`). Enter a character, such as a colon (`:`). @@ -102,6 +111,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the objects to export as CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to `ConvertTo-CSV`. @@ -119,6 +129,7 @@ Accept wildcard characters: False ``` ### -NoTypeInformation + Omits the type information header from the output. By default, the string in the output contains `#TYPE` followed by the fully-qualified name of the object type. @@ -135,6 +146,7 @@ Accept wildcard characters: False ``` ### -UseCulture + Uses the list separator for the current culture as the data delimiter. The default is a comma (`,`). @@ -154,19 +166,24 @@ 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). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object that has an Extended Type System (ETS) adapter to `ConvertTo-CSV`. ## OUTPUTS ### System.String + The CSV output is returned as a collection of strings. ## NOTES -* In CSV format, each object is represented by a comma-separated list of its property value. The property values are converted to strings (by using the `ToString()` method of the object), so they are generally represented by the name of the property value. `ConvertTo-CSV` does not export the methods of the object. + +- In CSV format, each object is represented by a comma-separated list of its property value. The property values are converted to strings (by using the `ToString()` method of the object), so they are generally represented by the name of the property value. `ConvertTo-CSV` does not export the methods of the object. The format of the resulting CSV strings is as follows: @@ -178,7 +195,7 @@ It contains a comma-separated list of the names of all the properties of the fir - The remaining strings consist of comma-separated lists of the property values of each object. -* When you submit multiple objects to `ConvertTo-CSV`, `ConvertTo-CSV` orders the strings based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is Null, as represented by two consecutive commas. If the remaining objects have additional properties, those property values are ignored. +- When you submit multiple objects to `ConvertTo-CSV`, `ConvertTo-CSV` orders the strings based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is Null, as represented by two consecutive commas. If the remaining objects have additional properties, those property values are ignored. ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Html.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Html.md index b3162bf91c4a..10928a037b90 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Html.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Html.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113290 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertTo-Html --- - # ConvertTo-Html + ## SYNOPSIS + Converts Microsoft .NET Framework objects into HTML that can be displayed in a Web browser. + ## SYNTAX ### Page (Default) + ``` ConvertTo-Html [-InputObject ] [[-Property] ] [[-Body] ] [[-Head] ] [[-Title] ] [-As ] [-CssUri ] [-PostContent ] [-PreContent ] @@ -21,12 +24,14 @@ ConvertTo-Html [-InputObject ] [[-Property] ] [[-Body] ] [[-Property] ] [-As ] [-Fragment] [-PostContent ] [-PreContent ] [] ``` ## DESCRIPTION + The ConvertTo-Html cmdlet converts .NET Framework objects into HTML that can be displayed in a Web browser. You can use this cmdlet to display the output of a command in a Web page. @@ -35,28 +40,34 @@ You can use the parameters of ConvertTo-Html to select object properties, to spe When you submit multiple objects to ConvertTo-Html, Windows PowerShell creates the table (or list) based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is an empty cell. If the remaining objects have additional properties, those property values are not included in the file. + ## EXAMPLES ### Example 1 -``` -PS C:\> convertto-html -inputobject (get-date) + +```powershell +ConvertTo-Html -InputObject (Get-Date) ``` This command creates an HTML page that displays the properties of the current date. It uses the InputObject parameter to submit the results of a Get-Date command to the ConvertTo-Html cmdlet. + ### Example 2 -``` -PS C:\> get-alias | convertto-html > aliases.htm -PS C:\> invoke-item aliases.htm + +```powershell +Get-Alias | ConvertTo-Html > aliases.htm +Invoke-Item aliases.htm ``` This command creates an HTML page that lists the Windows PowerShell aliases in the current console. The command uses the Get-Alias cmdlet to get the aliases. It uses the pipeline operator (|) to send the aliases to the ConvertTo-Html cmdlet, which creates the HTML page. + ### Example 3 -``` -PS C:\> get-eventlog -logname "Windows PowerShell" | convertto-html > pslog.htm + +```powershell +Get-EventLog -LogName "Windows PowerShell" | ConvertTo-Html > pslog.htm ``` This command creates an HTML page called pslog.htm that displays the events in the Windows PowerShell event log on the local computer. @@ -64,9 +75,11 @@ This command creates an HTML page called pslog.htm that displays the events in t It uses the Get-EventLog cmdlet to get the events in the Windows PowerShell log and then uses the pipeline operator (|) to send the events to the ConvertTo-Html cmdlet. The command also uses the redirection operator (\>) to send the HTML code to the pslog.htm file. + ### Example 4 -``` -PS C:\> get-process | convertto-html -property Name, Path, Company -title "Process Information" > proc.htm; ii proc.htm + +```powershell +Get-Process | ConvertTo-Html -Property Name, Path, Company -Title "Process Information" > proc.htm; ii proc.htm ``` These commands create and open an HTML page that lists the name, path, and company of the processes on the local computer. @@ -80,9 +93,11 @@ The command also uses the redirection operator (\>) to send the resulting HTML t The second command uses the Invoke-Item cmdlet (alias = ii) to open the Proc.htm in the default browser. The two commands are separated by a semicolon (;). + ### Example 5 + ``` -PS C:\> get-service | convertto-html -CssUri "test.css" +PS> get-service | convertto-html -CssUri "test.css" @@ -96,17 +111,21 @@ The command uses the CssUri parameter to specify a cascading style sheet for the The CssUri parameter adds an additional "\ get-service | convertto-html -as LIST > services.htm + +```powershell +Get-Service | ConvertTo-Html -As LIST > services.htm ``` This command creates an HTML page of the service objects that the Get-Service cmdlet returns. The command uses the As parameter to specify a list format. The redirection operator (\>) sends the resulting HTML to the Services.htm file. + ### Example 7 + ``` -PS C:\> get-date | cth -fragment +PS> get-date | cth -fragment ... @@ -123,9 +142,11 @@ It uses a pipeline operator (|) to send the results to the ConvertTo-Html cmdlet The ConvertTo-Html command includes the Fragment parameter, which limits the output to an HTML table. As a result, the other elements of an HTML page, such as the \ and \ tags, are omitted. + ### Example 8 -``` -PS C:\> get-eventlog -log "Windows PowerShell" | convertto-html -property id, level, task + +```powershell +Get-EventLog -LogName "Windows PowerShell" | ConvertTo-Html -Property id, level, task ``` This command uses the Get-EventLog cmdlet to get events from the "Windows PowerShell" event log. @@ -133,10 +154,12 @@ This command uses the Get-EventLog cmdlet to get events from the "Windows PowerS It uses a pipeline operator (|) to send the events to the ConvertTo-Html cmdlet, which converts the events to HTML format. The ConvertTo-Html command uses the Property parameter to select only the ID, Level, and Task properties of the event. + ### Example 9 + ``` -PS C:\> get-service A* | ConvertTo-Html -title "Windows Services: Server01" -body (get-date) -pre -"

Generated by Corporate IT

" -post "For details, contact Corporate IT." > services.htm; ii services.htm +PS> get-service A* | ConvertTo-Html -title "Windows Services: Server01" -body (get-date) -pre +"

Generated by Corporate IT

" -post "For details, contact Corporate IT." > services.htm; Invoke-Item services.htm ``` This command creates and opens a Web page that displays the services on the computer that begin with "A". @@ -147,9 +170,11 @@ The command uses a pipeline operator (|) to send the results to the ConvertTo-Ht The command uses a redirection operator (\>) to send the output to the Services.htm file. A semicolon (;) ends the first command and starts a second command, which uses the Invoke-Item cmdlet (alias = "ii") to open the Services.htm file in the default browser. + ## PARAMETERS ### -As + Determines whether the object is formatted as a table or a list. Valid values are TABLE and LIST. The default value is TABLE. @@ -174,6 +199,7 @@ Accept wildcard characters: False ``` ### -Body + Specifies the text to add after the opening \ tag. By default, there is no text in that position. @@ -190,6 +216,7 @@ Accept wildcard characters: False ``` ### -CssUri + Specifies the Uniform Resource Identifier (URI) of the cascading style sheet (CSS) that is applied to the HTML file. The URI is included in a style sheet link in the output. @@ -206,6 +233,7 @@ Accept wildcard characters: False ``` ### -Fragment + Generates only an HTML table. The HTML, HEAD, TITLE, and BODY tags are omitted. @@ -222,6 +250,7 @@ Accept wildcard characters: False ``` ### -Head + Specifies the content of the \ tag. The default is "\HTML TABLE\". If you use the Head parameter, the Title parameter is ignored. @@ -239,6 +268,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the objects to be represented in HTML. Enter a variable that contains the objects or type a command or expression that gets the objects. @@ -258,6 +288,7 @@ Accept wildcard characters: False ``` ### -PostContent + Specifies text to add after the closing \ tag. By default, there is no text in that position. @@ -274,6 +305,7 @@ Accept wildcard characters: False ``` ### -PreContent + Specifies text to add before the opening \ tag. By default, there is no text in that position. @@ -290,6 +322,7 @@ Accept wildcard characters: False ``` ### -Property + Includes the specified properties of the objects in the HTML. The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. @@ -311,6 +344,7 @@ Accept wildcard characters: False ``` ### -Title + Specifies a title for the HTML file, that is, the text that appears between the \ tags. ```yaml @@ -326,17 +360,24 @@ 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). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe any .NET object to ConvertTo-Html. + ## OUTPUTS ### System.String + ConvertTo-Html returns series of strings that comprise valid HTML. + ## NOTES -* To use this cmdlet, pipe one or more objects to the cmdlet or use the InputObject parameter to specify the object. When the input consists of multiple objects, the output of these two methods is quite different. + +- To use this cmdlet, pipe one or more objects to the cmdlet or use the InputObject parameter to specify the object. When the input consists of multiple objects, the output of these two methods is quite different. - When you pipe multiple objects to a cmdlet, Windows PowerShell sends the objects to the cmdlet one at a time. As a result, ConvertTo-Html creates a table that displays the individual objects. @@ -350,7 +391,6 @@ For example, if you use InputObject to submit the processes on a computer to Con (\) -* ## RELATED LINKS [ConvertTo-Csv](ConvertTo-Csv.md) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Json.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Json.md index 395e6c527a77..85f4c3648f08 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Json.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Json.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=217032 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertTo-Json --- - # ConvertTo-Json + ## SYNOPSIS + Converts an object to a JSON-formatted string + ## SYNTAX ``` @@ -18,6 +20,7 @@ ConvertTo-Json [-InputObject] [-Depth ] [-Compress] [ (Get-UICulture).Calendar | ConvertTo-Json +PS> (Get-UICulture).Calendar | ConvertTo-Json { @@ -56,18 +61,22 @@ PS C:\> (Get-UICulture).Calendar | ConvertTo-Json ``` This command uses the **ConvertTo-Json** cmdlet to convert a GregorianCalendar object to a JSON-formatted string. + ### Example 2 + ``` -PS C:\> @{Account="User01";Domain="Domain01";Admin="True"} | ConvertTo-Json - Compress +PS> @{Account="User01";Domain="Domain01";Admin="True"} | ConvertTo-Json - Compress {"Admin":"True","Account":"User01","Domain":"Domain01"} ``` This command shows the effect of using the Compress parameter of **ConvertTo-Json**. The compression affects only the appearance of the string, not its validity. + ### Example 3 + ``` The first command uses the **ConvertTo-Json** cmdlet to convert a **System.DateTime** object from the Get-Date cmdlet to a JSON-formatted string. The command uses the Select-Object cmdlet to get all (*) of the properties of the **DateTime** object.The output shows the JSON string that **ConvertTo-Json** returned. -PS C:\> Get-Date | Select-Object -Property * | ConvertTo-Json +PS> Get-Date | Select-Object -Property * | ConvertTo-Json { @@ -128,7 +137,7 @@ PS C:\> Get-Date | Select-Object -Property * | ConvertTo-Json } The second command uses ConvertFrom-Json to convert the JSON string to a JSON object. -PS C:\> Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json +PS> Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json DisplayHint : 2 @@ -168,16 +177,20 @@ Year : 2012 ``` This command shows how to use the ConvertTo-Json and ConvertFrom-Json cmdlet to convert an object to a JSON string and a JSON object. + ### Example 4 -``` -PS C:\> $JsonSecurityHelp = Get-Content $pshome\Modules\Microsoft.PowerShell.Security\en-US\Microsoft.PowerShell.Security.dll-Help.xml | ConvertTo-Json + +```powershell +$JsonSecurityHelp = Get-Content $pshome\Modules\Microsoft.PowerShell.Security\en-US\Microsoft.PowerShell.Security.dll-Help.xml | ConvertTo-Json ``` This command uses the **ConvertTo-Json** cmdlet to convert a Windows PowerShell help file from XML format to JSON format. You can use a command like this to use the help topic content in a web service application. + ## PARAMETERS ### -Compress + Omits white space and indented formatting in the output string. ```yaml @@ -193,6 +206,7 @@ Accept wildcard characters: False ``` ### -Depth + Specifies how many levels of contained objects are included in the JSON representation. The default value is 2. @@ -209,6 +223,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the objects to convert to JSON format. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe an object to **ConvertTo-Json**. @@ -230,17 +245,22 @@ 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). + ## INPUTS ### System.Object + You can pipe any object to **ConvertTo-Json**. + ## OUTPUTS ### System.String ## NOTES -* The **ConvertTo-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). + +- The **ConvertTo-Json** cmdlet is implemented by using the [JavaScriptSerializer class](https://msdn.microsoft.com/library/system.web.script.serialization.javascriptserializer). ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index 639c54785f8b..506efde9732d 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,18 +7,21 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135204 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: ConvertTo-Xml --- - # ConvertTo-Xml + ## SYNOPSIS + Creates an XML-based representation of an object. + ## SYNTAX -```powershell +``` ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] [-As ] [] ``` ## DESCRIPTION + The `ConvertTo-Xml` cmdlet creates an XML-based representation of one or more Microsoft .NET Framework objects. To use this cmdlet, pipe one or more objects to the cmdlet, or use the **InputObject** parameter to specify the object. @@ -30,21 +33,26 @@ This cmdlet is similar to `Export-Clixml` except that `Export-Clixml` stores the ## EXAMPLES ### Example 1 -``` -PS C:\> get-date | convertto-xml + +```powershell +Get-Date | ConvertTo-Xml ``` This command converts the current date (a DateTime object) to XML. + ### Example 2 -``` -PS C:\> convertto-xml -as Document -inputObject (get-process) -depth 3 + +```powershell +ConvertTo-Xml -As Document -InputObject (Get-Process) -Depth 3 ``` This command converts the process objects that represent all of the processes on the computer into an XML document. The objects are expanded to a depth of three levels. + ## PARAMETERS ### -As + Determines the output format. Valid values are: @@ -67,6 +75,7 @@ Accept wildcard characters: False ``` ### -Depth + Specifies how many levels of contained objects are included in the XML representation. The default value is 1. @@ -88,6 +97,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-XML. @@ -105,6 +115,7 @@ Accept wildcard characters: True ``` ### -NoTypeInformation + Omits the Type attribute from the object nodes. ```yaml @@ -120,15 +131,21 @@ 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). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object to ConvertTo-XML. + ## OUTPUTS ### System.String or System.Xml.XmlDocument + The value of the As parameter determines the type of object that ConvertTo-XML returns. + ## NOTES ## RELATED LINKS
DisplayHintDateTimeDateDayDayOfWeekDayOfYearHour